phronomy 0.27.0 → 0.29.0

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

@@ -9,86 +9,102 @@ module Phronomy
         def initialize(view) = @view = view
 
         def create_active(execution)
-          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::TeamStorageSchema::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)
+          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(execution.team_id) 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)
-          value = @view.atomic do |bound|
-            entry = bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).read(team_execution_id.to_s)
-            entry && decode(entry, 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
-          value || raise(Phronomy::Storage::NotFoundError, "TeamExecution not found: #{team_execution_id}")
         end
 
         def save(team_execution_id, expected_revision:, execution:)
-          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::TeamStorageSchema::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?)
+          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(execution.team_id) 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)
-          @view.atomic do |bound|
-            bound.records(Phronomy::TeamStorageSchema::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
+          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)
-          raise ArgumentError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit.positive?
-          @view.atomic do |bound|
-            bound.records(Phronomy::TeamStorageSchema::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
+          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)
-          @view.records(Phronomy::TeamStorageSchema::EXECUTIONS).delete(key: team_execution_id.to_s)
+          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)
-          @view.records(Phronomy::TeamStorageSchema::EXECUTIONS).delete_matching(index: :owner, equals: {owner: team_id.to_s})
+          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)
-          condition = Phronomy::Storage::Condition::NoRows.new(resource: Phronomy::TeamStorageSchema::EXECUTIONS,
-            index: :owner_active, equals: {owner: team_id.to_s, active: true})
-          @view.check!(guards: [Phronomy::Storage::GuardRef.new(resource: Phronomy::TeamStorageSchema::ROOTS, key: team_id.to_s)],
-            conditions: [condition])
-        rescue Phronomy::Storage::ConditionFailedError => error
-          raise unless error.condition.equal?(condition)
-          raise Phronomy::AgentBusyError, error.message
+          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::MultiAgent::TeamBusyError.new(error.message, team_id: team_id), cause: error
+          end
         end
 
         private
 
         def attributes(execution) = {owner: execution.team_id.to_s, active: execution.active?}
 
-        def admission
+        def admission(team_id)
           yield
         rescue Phronomy::Storage::UniqueConstraintError => error
-          raise unless error.resource == Phronomy::TeamStorageSchema::EXECUTIONS.id && error.constraint == :one_active_owner
-          raise Phronomy::AgentBusyError, error.message
+          raise unless error.resource == Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS.id && error.constraint == :one_active_owner
+          raise Phronomy::MultiAgent::TeamBusyError.new(error.message, team_id: team_id), cause: error
         end
 
         def decode(entry, team_execution_id, owner: nil, revision: nil, active: nil)

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

@@ -9,39 +9,47 @@ module Phronomy
         def initialize(view) = @view = view
 
         def create(root)
-          record = Codec.encode_team_root(root)
-          @view.atomic do |bound|
-            entry = bound.records(Phronomy::TeamStorageSchema::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)
+          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)
-          value = @view.atomic do |bound|
-            entry = bound.records(Phronomy::TeamStorageSchema::ROOTS).read(team_id.to_s)
-            entry && decode(entry, 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
-          value || raise(Phronomy::Storage::NotFoundError, "Team not found: #{team_id}")
         end
 
         def save(team_id, expected_revision:, root:)
-          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::TeamStorageSchema::ROOTS).replace(key: team_id.to_s,
-              expected_revision: expected, next_revision: revision, attributes: {}, record: record)
-            decode(entry, team_id, revision: revision)
+          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)
-          @view.records(Phronomy::TeamStorageSchema::ROOTS).delete(key: team_id.to_s)
+          Phronomy::Persistence::StorageBoundary.call do
+            @view.records(Phronomy::MultiAgent::Persistence::StorageSchema::ROOTS).delete(key: team_id.to_s)
+          end
         end
 
         private

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/multi_agent/shared_state.rb

@@ -188,7 +188,7 @@ module Phronomy
       end
 
       def build_read_tool(store)
-        Class.new(Phronomy::Agent::Context::Capability::Base) do
+        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."
@@ -199,7 +199,7 @@ module Phronomy
       end
 
       def build_write_tool(store, cycle, agent_key)
-        Class.new(Phronomy::Agent::Context::Capability::Base) do
+        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."

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

data/lib/phronomy/multi_agent/team_busy_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module MultiAgent
+    # Describes the Team itself, not a child Agent.
+    # @api public
+    class TeamBusyError < Phronomy::Error
+      attr_reader :team_id
+
+      def initialize(message = nil, team_id:)
+        @team_id = team_id.to_s.dup.freeze
+        super(message || "Team #{@team_id}: busy", code: "team.busy")
+      end
+    end
+  end
+end