phronomy 0.22.0 → 0.23.0

data/lib/phronomy/engine/event_loop.rb

@@ -4,19 +4,56 @@ module Phronomy
   # Runtime-owned FIFO event loop for FSMSession instances.
   #
   # EventLoop owns the framework's sole control-plane OS thread. All session
-  # lifecycle progression happens by short event dispatches on this thread.
+  # lifecycle progression and Phronomy-managed live execution-state mutation
+  # happens by short event dispatches on this thread.
   class EventLoop
     SYSTEM_CHANNEL_ID = "__event_loop__"
 
     QUEUE_BACKLOG_WARNING_THRESHOLD = 1_000
     QUEUE_BACKLOG_WARNING_INTERVAL_SECONDS = 60.0
 
-    TERMINAL_MANAGEMENT_EVENTS = %i[finished halted error].freeze
+    TERMINAL_MANAGEMENT_EVENTS = %i[finished halted error recovery_required].freeze
     private_constant :TERMINAL_MANAGEMENT_EVENTS
 
     STOP = Object.new.freeze
     WAKE = Object.new.freeze
-    private_constant :STOP, :WAKE
+    UNSET = Object.new.freeze
+    private_constant :STOP, :WAKE, :UNSET
+
+    # Immutable EventLoop-owned value. The map containing these records is the
+    # mutable authority; records are replaced rather than mutated in place.
+    AgentExecutionState = Data.define(
+      :execution_id,
+      :agent,
+      :coordinator,
+      :execution,
+      :runtime_projection,
+      :base_manifest,
+      :invocation,
+      :fsm_session_id
+    )
+    private_constant :AgentExecutionState
+
+    # Read-only process-local lookup view used by approval/live-owner APIs.
+    # It intentionally exposes no mutable execution, invocation, or projection.
+    AgentExecutionOwner = Data.define(:execution_id, :agent, :coordinator, :status)
+    private_constant :AgentExecutionOwner
+
+    # EventLoop-owned process-local top-level execution admission. This is
+    # separate from AgentExecutionState because admission begins before the
+    # durable AgentExecution exists. owner_token is coordination-only and is
+    # never a semantic result-authority identifier.
+    AgentAdmission = Data.define(:agent_id, :owner_token, :execution_id, :state)
+    private_constant :AgentAdmission
+
+    # EventLoop-owned process-local Workflow execution-segment admission. The
+    # owner token is a Runtime coordination capability, not a domain identity or
+    # routing identity. fsm_session_id is bound only after durable load/hydration
+    # completes and a concrete FSMSession has been constructed.
+    WorkflowAdmission = Data.define(
+      :workflow_instance_id, :owner_token, :fsm_session_id, :state
+    )
+    private_constant :WorkflowAdmission
 
     def initialize(runtime:)
       @runtime = runtime
@@ -28,8 +65,13 @@ module Phronomy
 
       @fsms = {}
       @waiting = {}
-      @admitted_session_ids = Set.new
+      @admitted_fsm_session_ids = Set.new
       @workflow_admissions = {}
+      @agent_admissions = {}
+      @agent_executions = {}
+      @agent_completion_waiters = Hash.new { |hash, key| hash[key] = [] }
+      @agent_inflight_work = Hash.new { |hash, key| hash[key] = {} }
+      @agent_deferred_terminals = {}
 
       @lifecycle_mutex = Mutex.new
       @idle_cond = ConditionVariable.new
@@ -88,17 +130,17 @@ module Phronomy
 
       @lifecycle_mutex.synchronize do
         ensure_accepting_registrations!
-        if @admitted_session_ids.include?(fsm_session.id)
+        if @admitted_fsm_session_ids.include?(fsm_session.id)
           raise Phronomy::Error,
             "FSMSession #{fsm_session.id.inspect} is already registered"
         end
 
-        @admitted_session_ids.add(fsm_session.id)
+        @admitted_fsm_session_ids.add(fsm_session.id)
         @outstanding_sessions += 1
         begin
           queued_depth = enqueue([event, monotonic_nanoseconds])
         rescue
-          @admitted_session_ids.delete(fsm_session.id)
+          @admitted_fsm_session_ids.delete(fsm_session.id)
           @outstanding_sessions -= 1
           @idle_cond.broadcast if runtime_idle_locked?
           raise
@@ -114,16 +156,16 @@ module Phronomy
       accepted = @lifecycle_mutex.synchronize do
         next false unless accepting_events?
 
-        terminal_session_id = nil
+        terminal_fsm_session_id = nil
         if terminal_management_event?(event)
-          terminal_session_id = event.payload.fetch(:session_id)
-          @admitted_session_ids.delete(terminal_session_id)
+          terminal_fsm_session_id = event.payload.fetch(:fsm_session_id)
+          @admitted_fsm_session_ids.delete(terminal_fsm_session_id)
         end
 
         begin
           queued_depth = enqueue([event, monotonic_nanoseconds])
         rescue
-          @admitted_session_ids.add(terminal_session_id) if terminal_session_id
+          @admitted_fsm_session_ids.add(terminal_fsm_session_id) if terminal_fsm_session_id
           raise
         end
         true
@@ -142,7 +184,7 @@ module Phronomy
       queued_depth = nil
       accepted = @lifecycle_mutex.synchronize do
         next false unless accepting_events?
-        next false unless @admitted_session_ids.include?(event.target_id)
+        next false unless @admitted_fsm_session_ids.include?(event.target_id)
 
         queued_depth = enqueue([event, monotonic_nanoseconds])
         true
@@ -153,36 +195,452 @@ module Phronomy
       true
     end
 
-    # Reserves one logical Workflow thread for one concrete FSMSession execution.
-    # thread_id is durable Workflow identity; owner_fsm_session_id is the
-    # Runtime-only identity of the invocation/resume that currently owns it.
-    def admit_workflow(thread_id, owner_fsm_session_id:)
-      key = thread_id.to_s
-      owner = owner_fsm_session_id.to_s
-      raise ArgumentError, "thread_id must not be empty" if key.empty?
-      raise ArgumentError, "owner_fsm_session_id must not be empty" if owner.empty?
+    # Process-local read-only admission check used by destructive Agent lifecycle
+    # operations. The mutable admission map itself remains EventLoop-owned.
+    def agent_execution_admitted?(agent_id)
+      @lifecycle_mutex.synchronize { @agent_admissions.key?(agent_id.to_s) }
+    end
+
+    # Reserves the one top-level logical execution slot for agent_id before any
+    # Persistence execution admission is attempted.
+    # @api private
+    def admit_agent_execution(agent_id, owner_token:)
+      assert_event_loop_thread!
+      key = agent_id.to_s
+      raise ArgumentError, "agent_id must not be empty" if key.empty?
+      raise ArgumentError, "owner_token is required" unless owner_token
+
+      @lifecycle_mutex.synchronize do
+        ensure_accepting_registrations!
+        if @agent_admissions.key?(key)
+          raise Phronomy::AgentBusyError,
+            "Agent #{key.inspect} already has a nonterminal top-level execution"
+        end
+        @agent_admissions[key] = AgentAdmission.new(
+          agent_id: key.freeze,
+          owner_token: owner_token,
+          execution_id: nil,
+          state: :admitting
+        )
+      end
+      true
+    end
+
+    # Binds a successful durable AgentExecution identity to the earlier
+    # process-local admission.
+    # @api private
+    def bind_agent_execution_admission(agent_id, owner_token:, execution_id:)
+      assert_event_loop_thread!
+      key = agent_id.to_s
+      execution_key = execution_id.to_s
+      @lifecycle_mutex.synchronize do
+        current = @agent_admissions.fetch(key) do
+          raise Phronomy::Error, "Agent #{key.inspect} has no Runtime admission"
+        end
+        unless current.owner_token.equal?(owner_token) && current.execution_id.nil?
+          raise Phronomy::Error, "stale Agent admission bind for #{key.inspect}"
+        end
+        @agent_admissions[key] = AgentAdmission.new(
+          agent_id: current.agent_id,
+          owner_token: current.owner_token,
+          execution_id: execution_key.freeze,
+          state: :executing
+        )
+      end
+      true
+    end
+
+    # @api private
+    def mark_agent_execution_admission(agent_id, execution_id:, state:)
+      assert_event_loop_thread!
+      key = agent_id.to_s
+      execution_key = execution_id.to_s
+      next_state = state.to_sym
+      unless %i[executing suspended resuming cancelling terminalizing recovery_required].include?(next_state)
+        raise ArgumentError, "unsupported Agent admission state: #{next_state.inspect}"
+      end
+
+      @lifecycle_mutex.synchronize do
+        current = @agent_admissions.fetch(key) do
+          raise Phronomy::Error, "Agent #{key.inspect} has no Runtime admission"
+        end
+        unless current.execution_id.to_s == execution_key
+          raise Phronomy::Error, "stale Agent admission state update for #{key.inspect}"
+        end
+        @agent_admissions[key] = AgentAdmission.new(
+          agent_id: current.agent_id,
+          owner_token: current.owner_token,
+          execution_id: current.execution_id,
+          state: next_state
+        )
+        @idle_cond.broadcast if runtime_idle_locked?
+      end
+      true
+    end
+
+    # @api private
+    def mark_agent_admission_recovery_required(agent_id, owner_token:)
+      assert_event_loop_thread!
+      key = agent_id.to_s
+      @lifecycle_mutex.synchronize do
+        current = @agent_admissions.fetch(key) do
+          raise Phronomy::Error, "Agent #{key.inspect} has no Runtime admission"
+        end
+        unless current.owner_token.equal?(owner_token)
+          raise Phronomy::Error, "stale Agent admission recovery update for #{key.inspect}"
+        end
+        @agent_admissions[key] = AgentAdmission.new(
+          agent_id: current.agent_id,
+          owner_token: current.owner_token,
+          execution_id: current.execution_id,
+          state: :recovery_required
+        )
+        @idle_cond.broadcast if runtime_idle_locked?
+      end
+      true
+    end
+
+    # Owner-aware release. Pre-durable failures release by owner_token; durable
+    # terminal outcomes release by execution_id.
+    # @api private
+    def release_agent_execution_admission(agent_id, owner_token: nil, execution_id: nil)
+      assert_event_loop_thread!
+      key = agent_id.to_s
+      @lifecycle_mutex.synchronize do
+        current = @agent_admissions[key]
+        next false unless current
+
+        authoritative = if execution_id
+          current.execution_id.to_s == execution_id.to_s
+        elsif owner_token
+          current.owner_token.equal?(owner_token)
+        else
+          false
+        end
+        next false unless authoritative
+
+        @agent_admissions.delete(key)
+        @idle_cond.broadcast if runtime_idle_locked?
+        true
+      end
+    end
+
+    # Process-local read-only owner lookup. Mutable Agent execution state never
+    # crosses this boundary; external callers receive only routing/ownership data.
+    def agent_execution_owner(execution_id)
+      key = execution_id.to_s
+      @lifecycle_mutex.synchronize do
+        state = @agent_executions[key]
+        next nil unless state
+
+        AgentExecutionOwner.new(
+          execution_id: key.freeze,
+          agent: state.agent,
+          coordinator: state.coordinator,
+          status: state.execution.status
+        )
+      end
+    end
+
+    # EventLoop-only accessors below form the live Agent execution authority.
+    # Offload workers receive operation-specific immutable snapshots instead.
+    # @api private
+    def agent_execution_state(execution_id)
+      assert_event_loop_thread!
+      @agent_executions[execution_id.to_s]
+    end
+
+    # @api private
+    def install_agent_execution(
+      execution_id:,
+      agent:,
+      coordinator:,
+      execution:,
+      runtime_projection:,
+      base_manifest:,
+      invocation:,
+      fsm_session_id:
+    )
+      assert_event_loop_thread!
+      key = execution_id.to_s
+      state = AgentExecutionState.new(
+        execution_id: key.freeze,
+        agent: agent,
+        coordinator: coordinator,
+        execution: execution,
+        runtime_projection: runtime_projection,
+        base_manifest: base_manifest,
+        invocation: invocation,
+        fsm_session_id: fsm_session_id&.to_s&.freeze
+      )
+      @lifecycle_mutex.synchronize do
+        if @agent_executions.key?(key)
+          raise Phronomy::Error, "Agent execution #{key.inspect} is already live"
+        end
+        @agent_executions[key] = state
+      end
+      state
+    end
+
+    # @api private
+    def replace_agent_execution(
+      execution_id,
+      execution: UNSET,
+      runtime_projection: UNSET,
+      invocation: UNSET,
+      fsm_session_id: UNSET
+    )
+      assert_event_loop_thread!
+      key = execution_id.to_s
+      @lifecycle_mutex.synchronize do
+        current = @agent_executions.fetch(key) do
+          raise Phronomy::Error, "Agent execution #{key.inspect} is not live"
+        end
+        updated = AgentExecutionState.new(
+          execution_id: current.execution_id,
+          agent: current.agent,
+          coordinator: current.coordinator,
+          execution: execution.equal?(UNSET) ? current.execution : execution,
+          runtime_projection: runtime_projection.equal?(UNSET) ?
+            current.runtime_projection : runtime_projection,
+          base_manifest: current.base_manifest,
+          invocation: invocation.equal?(UNSET) ? current.invocation : invocation,
+          fsm_session_id: fsm_session_id.equal?(UNSET) ?
+            current.fsm_session_id : fsm_session_id&.to_s&.freeze
+        )
+        @agent_executions[key] = updated
+        updated
+      end
+    end
+
+    # Registers a caller-facing Task that observes the authoritative terminal
+    # outcome of one logical Agent execution. Waiters are Runtime-only and are
+    # never persisted or rehydrated.
+    # @api private
+    def register_agent_completion_waiter(execution_id, task)
+      assert_event_loop_thread!
+      unless task.is_a?(Phronomy::Task)
+        raise ArgumentError, "Agent completion waiter must be a Phronomy::Task"
+      end
+
+      key = execution_id.to_s
+      @lifecycle_mutex.synchronize do
+        waiters = @agent_completion_waiters[key]
+        waiters << task unless waiters.include?(task)
+      end
+      task
+    end
+
+    # Atomically detaches all process-local completion waiters at authoritative
+    # terminal delivery. A fallback Task is included for pre-install terminal
+    # paths that never acquired a live execution directory entry.
+    # @api private
+    def take_agent_completion_waiters(execution_id, fallback: nil)
+      assert_event_loop_thread!
+      key = execution_id.to_s
+      @lifecycle_mutex.synchronize do
+        waiters = @agent_completion_waiters.delete(key) || []
+        waiters << fallback if fallback && !waiters.include?(fallback)
+        waiters
+      end
+    end
+
+    # Registers one execution-owned asynchronous operation for physical
+    # quiescence supervision. OffloadPool tasks expose a private physical
+    # completion signal; custom asynchronous handles are required to make their
+    # ordinary completion mean that no residual execution-affecting work remains.
+    # @api private
+    def supervise_agent_operation(execution_id, operation)
+      assert_event_loop_thread!
+      key = execution_id.to_s
+      unless operation.respond_to?(:on_complete)
+        raise ArgumentError, "supervised operation must expose on_complete"
+      end
+
+      physically_done = if operation.respond_to?(:physical_complete?)
+        operation.physical_complete?
+      elsif operation.respond_to?(:done?)
+        operation.done?
+      else
+        false
+      end
+      return operation if physically_done
+
+      token = Object.new.freeze
+      @lifecycle_mutex.synchronize do
+        unless @agent_executions.key?(key)
+          raise Phronomy::Error, "Agent execution #{key.inspect} is not live"
+        end
+        @agent_inflight_work[key][token] = true
+      end
+
+      callback = lambda do
+        accepted = post(
+          Phronomy::Event.new(
+            type: :agent_physical_work_completed,
+            target_id: SYSTEM_CHANNEL_ID,
+            payload: {execution_id: key, token: token}.freeze
+          )
+        )
+        unless accepted
+          Phronomy.configuration.logger&.warn(
+            "[Phronomy] EventLoop rejected physical-completion delivery for #{key}"
+          )
+        end
+      end
+
+      if operation.respond_to?(:on_physical_complete)
+        operation.on_physical_complete(&callback)
+      else
+        operation.on_complete { |_value, _error| callback.call }
+      end
+      operation
+    end
+
+    # @api private
+    def agent_execution_quiescent?(execution_id)
+      assert_event_loop_thread!
+      key = execution_id.to_s
+      @lifecycle_mutex.synchronize do
+        work = @agent_inflight_work.fetch(key, nil)
+        work.nil? || work.empty?
+      end
+    end
+
+    # Holds exactly one terminal continuation while cancellation/deadline has
+    # revoked result authority but execution-owned physical work is still live.
+    # @api private
+    def defer_agent_terminal_until_quiescent(execution_id, command)
+      assert_event_loop_thread!
+      key = execution_id.to_s
+      @lifecycle_mutex.synchronize do
+        if @agent_deferred_terminals.key?(key)
+          raise Phronomy::Error, "Agent execution #{key.inspect} already has a deferred terminal"
+        end
+        @agent_deferred_terminals[key] = command
+      end
+      true
+    end
+
+    # @api private
+    def agent_inflight_work_count(execution_id)
+      key = execution_id.to_s
+      @lifecycle_mutex.synchronize do
+        (@agent_inflight_work.fetch(key, nil) || {}).size
+      end
+    end
+
+    # @api private
+    def release_agent_execution(execution_id)
+      assert_event_loop_thread!
+      key = execution_id.to_s
+      @lifecycle_mutex.synchronize do
+        work = @agent_inflight_work.fetch(key, nil)
+        unless work.nil? || work.empty?
+          raise Phronomy::Error,
+            "cannot release non-quiescent Agent execution #{key.inspect}"
+        end
+        if @agent_deferred_terminals.key?(key)
+          raise Phronomy::Error,
+            "cannot release Agent execution #{key.inspect} with deferred terminal work"
+        end
+        @agent_inflight_work.delete(key)
+        @agent_executions.delete(key)
+      end
+    end
+
+    # @api private
+    def fsm_session_state(fsm_session_id)
+      assert_event_loop_thread!
+      @fsms[fsm_session_id.to_s]&.current_state
+    end
+
+    # Reserves one logical Workflow execution segment before durable load or
+    # hydration. The owner token is independent from any later FSMSession id.
+    # @api private
+    def admit_workflow(workflow_instance_id, owner_token:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      raise ArgumentError, "workflow_instance_id must not be empty" if key.empty?
+      raise ArgumentError, "owner_token is required" unless owner_token
 
       @lifecycle_mutex.synchronize do
         ensure_accepting_registrations!
-        current_owner = @workflow_admissions[key]
-        if current_owner
+        if @workflow_admissions.key?(key)
           raise Phronomy::Error,
-            "Workflow thread #{key.inspect} is already owned by " \
-            "FSMSession #{current_owner.inspect}"
+            "Workflow instance #{key.inspect} already has a live execution segment"
+        end
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: key.freeze,
+          owner_token: owner_token,
+          fsm_session_id: nil,
+          state: :admitting
+        )
+      end
+      true
+    end
+
+    # Binds the concrete routing identity after admission and durable hydration.
+    # @api private
+    def bind_workflow_session(workflow_instance_id, owner_token:, fsm_session_id:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      fsm_key = fsm_session_id.to_s
+      raise ArgumentError, "fsm_session_id must not be empty" if fsm_key.empty?
+
+      @lifecycle_mutex.synchronize do
+        current = @workflow_admissions.fetch(key) do
+          raise Phronomy::Error, "Workflow instance #{key.inspect} has no Runtime admission"
+        end
+        unless current.owner_token.equal?(owner_token) && current.fsm_session_id.nil?
+          raise Phronomy::Error, "stale Workflow admission bind for #{key.inspect}"
+        end
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: current.workflow_instance_id,
+          owner_token: current.owner_token,
+          fsm_session_id: fsm_key.freeze,
+          state: :executing
+        )
+      end
+      true
+    end
+
+    # @api private
+    def mark_workflow_admission(workflow_instance_id, owner_token:, state:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      next_state = state.to_sym
+      unless %i[executing persisting_terminal recovery_required].include?(next_state)
+        raise ArgumentError, "unsupported Workflow admission state: #{next_state.inspect}"
+      end
+
+      @lifecycle_mutex.synchronize do
+        current = @workflow_admissions.fetch(key) do
+          raise Phronomy::Error, "Workflow instance #{key.inspect} has no Runtime admission"
+        end
+        unless current.owner_token.equal?(owner_token)
+          raise Phronomy::Error, "stale Workflow admission update for #{key.inspect}"
         end
-        @workflow_admissions[key] = owner
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: current.workflow_instance_id,
+          owner_token: current.owner_token,
+          fsm_session_id: current.fsm_session_id,
+          state: next_state
+        )
+        @idle_cond.broadcast if runtime_idle_locked?
       end
       true
     end
 
-    # Releases a Workflow reservation only when the caller is its current owner.
-    # A failed competing admission can therefore never release another session's
-    # reservation during cleanup.
-    def release_workflow(thread_id, owner_fsm_session_id:)
-      key = thread_id.to_s
-      owner = owner_fsm_session_id.to_s
+    # Owner-aware release. A competing or stale attempt cannot release the
+    # current Workflow execution segment.
+    # @api private
+    def release_workflow(workflow_instance_id, owner_token:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
       @lifecycle_mutex.synchronize do
-        next false unless @workflow_admissions[key] == owner
+        current = @workflow_admissions[key]
+        next false unless current&.owner_token&.equal?(owner_token)
 
         @workflow_admissions.delete(key)
         @idle_cond.broadcast if runtime_idle_locked?
@@ -190,25 +648,40 @@ module Phronomy
       end
     end
 
-    def workflow_admission_owner(thread_id)
-      @lifecycle_mutex.synchronize { @workflow_admissions[thread_id.to_s] }
+    # Read-only diagnostics used by internal tests and routing assertions.
+    def workflow_admission_owner(workflow_instance_id)
+      @lifecycle_mutex.synchronize do
+        @workflow_admissions[workflow_instance_id.to_s]&.owner_token
+      end
+    end
+
+    def workflow_admission_fsm_session_id(workflow_instance_id)
+      @lifecycle_mutex.synchronize do
+        @workflow_admissions[workflow_instance_id.to_s]&.fsm_session_id
+      end
     end
 
-    # Resolves durable Workflow identity to the currently owning FSMSession and
-    # enqueues the event atomically with that ownership check.
-    def post_to_workflow(thread_id:, event:, payload: nil)
+    def workflow_admission_state(workflow_instance_id)
+      @lifecycle_mutex.synchronize do
+        @workflow_admissions[workflow_instance_id.to_s]&.state
+      end
+    end
+
+    def post_to_workflow(workflow_instance_id:, event:, payload: nil)
       queued_depth = nil
       posted_event = nil
       accepted = @lifecycle_mutex.synchronize do
         next false unless accepting_events?
 
-        owner = @workflow_admissions[thread_id.to_s]
-        next false unless owner
-        next false unless @admitted_session_ids.include?(owner)
+        admission = @workflow_admissions[workflow_instance_id.to_s]
+        next false unless admission&.state == :executing
+        fsm_session_id = admission.fsm_session_id
+        next false unless fsm_session_id
+        next false unless @admitted_fsm_session_ids.include?(fsm_session_id)
 
         posted_event = Phronomy::Event.new(
           type: event.to_sym,
-          target_id: owner,
+          target_id: fsm_session_id,
           payload: payload
         )
         queued_depth = enqueue([posted_event, monotonic_nanoseconds])
@@ -220,7 +693,6 @@ module Phronomy
       true
     end
 
-    # Interrupts the queue wait so EventLoop can recompute the next timer deadline.
     def wake
       @queue.push(WAKE)
       true
@@ -228,8 +700,8 @@ module Phronomy
       false
     end
 
-    def admitted_session?(session_id)
-      @lifecycle_mutex.synchronize { @admitted_session_ids.include?(session_id) }
+    def admitted_fsm_session?(fsm_session_id)
+      @lifecycle_mutex.synchronize { @admitted_fsm_session_ids.include?(fsm_session_id) }
     end
 
     def current?
@@ -262,8 +734,6 @@ module Phronomy
       end
     end
 
-    # Sends STOP to the queue and joins the EventLoop thread.
-    # Assumes sessions have already been drained before this call.
     def stop_and_join(deadline:)
       @shutdown_mutex.synchronize do
         return @shutdown_status if @shutdown_status
@@ -288,7 +758,6 @@ module Phronomy
       end
     end
 
-    # Legacy entry point kept for any callers that pass deadline:/cancel_grace:.
     def shutdown(deadline:, cancel_grace: deadline)
       stop_and_join(deadline: deadline)
     end
@@ -297,7 +766,6 @@ module Phronomy
       @thread&.alive? || false
     end
 
-    # Compatibility for existing runtime/shutdown observers during migration.
     alias_method :task_alive?, :thread_alive?
 
     private
@@ -352,12 +820,9 @@ module Phronomy
     def dispatch_management(event)
       case event.type
       when :finished, :halted, :error
-        session_id = event.payload.fetch(:session_id)
-        session = @fsms.delete(session_id)
-        waiter = @waiting.delete(session_id)
-        # decrement before waking caller so wait_until_idle sees the control-plane
-        # session count immediately; Workflow durable admission may intentionally
-        # keep Runtime non-idle until its terminal save completes.
+        fsm_session_id = event.payload.fetch(:fsm_session_id)
+        session = @fsms.delete(fsm_session_id)
+        waiter = @waiting.delete(fsm_session_id)
         decrement_outstanding if session
         complete_waiter(waiter, event.payload.fetch(:result))
       when :start
@@ -366,12 +831,21 @@ module Phronomy
         @fsms[session.id] = session
         @waiting[session.id] = waiter if waiter
         session.start
-      when :agent_terminal_ready
+      when :agent_control, :agent_terminal_ready
+        # :agent_terminal_ready is retained as an internal migration-compatible
+        # dispatch name; ACS-11 emits the operation-neutral :agent_control event.
         cmd = event.payload.fetch(:command)
         cmd.coordinator.deliver_on_event_loop(cmd)
-      when :workflow_persistence_ready
+      when :agent_physical_work_completed
+        complete_agent_physical_work(event.payload)
+      when :workflow_control
         cmd = event.payload.fetch(:command)
-        cmd.runner.deliver_persistence_on_event_loop(cmd)
+        cmd.runner.deliver_on_event_loop(cmd)
+      when :recovery_required
+        fsm_session_id = event.payload.fetch(:fsm_session_id)
+        session = @fsms.delete(fsm_session_id)
+        decrement_outstanding if session
+        mark_workflow_recovery_required_for_session(fsm_session_id)
       end
     end
 
@@ -379,7 +853,43 @@ module Phronomy
       event.target_id == SYSTEM_CHANNEL_ID &&
         TERMINAL_MANAGEMENT_EVENTS.include?(event.type) &&
         event.payload.is_a?(Hash) &&
-        event.payload.key?(:session_id)
+        event.payload.key?(:fsm_session_id)
+    end
+
+    def complete_agent_physical_work(payload)
+      key = payload.fetch(:execution_id).to_s
+      token = payload.fetch(:token)
+      deferred = @lifecycle_mutex.synchronize do
+        work = @agent_inflight_work.fetch(key, nil)
+        next nil unless work&.delete(token)
+
+        if work.empty?
+          @agent_inflight_work.delete(key)
+          command = @agent_deferred_terminals.delete(key)
+          @idle_cond.broadcast if runtime_idle_locked?
+          command
+        end
+      end
+      deferred&.coordinator&.deliver_on_event_loop(deferred)
+      true
+    end
+
+    def mark_workflow_recovery_required_for_session(fsm_session_id)
+      @lifecycle_mutex.synchronize do
+        key, admission = @workflow_admissions.find do |_workflow_instance_id, candidate|
+          candidate.fsm_session_id == fsm_session_id.to_s
+        end
+        return false unless admission
+
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: admission.workflow_instance_id,
+          owner_token: admission.owner_token,
+          fsm_session_id: nil,
+          state: :recovery_required
+        )
+        @idle_cond.broadcast if runtime_idle_locked?
+      end
+      true
     end
 
     def begin_stopping_if_idle
@@ -406,9 +916,19 @@ module Phronomy
       @waiting.values.each { |waiter| complete_waiter(waiter, error) }
       @waiting.clear
       @fsms.clear
+      completion_waiters = @lifecycle_mutex.synchronize do
+        waiters = @agent_completion_waiters.values.flatten
+        @agent_completion_waiters.clear
+        @agent_inflight_work.clear
+        @agent_deferred_terminals.clear
+        waiters
+      end
+      completion_waiters.each { |waiter| complete_waiter(waiter, error) }
       @lifecycle_mutex.synchronize do
-        @admitted_session_ids.clear
+        @admitted_fsm_session_ids.clear
         @workflow_admissions.clear
+        @agent_admissions.clear
+        @agent_executions.clear
         @outstanding_sessions = 0
         @idle_cond.broadcast
       end
@@ -427,8 +947,10 @@ module Phronomy
     def notify_unexpected_dispatcher_failure(error)
       @lifecycle_mutex.synchronize do
         @state = :failed
-        @admitted_session_ids.clear
+        @admitted_fsm_session_ids.clear
         @workflow_admissions.clear
+        @agent_admissions.clear
+        @agent_executions.clear
         @idle_cond.broadcast
       end
       cleanup_abandoned_work(error)
@@ -445,6 +967,13 @@ module Phronomy
         "EventLoop is #{@state}; new sessions are not accepted"
     end
 
+    def assert_event_loop_thread!
+      return if current?
+
+      raise Phronomy::Error,
+        "Phronomy-managed live execution state may only be mutated on EventLoop"
+    end
+
     def decrement_outstanding
       @lifecycle_mutex.synchronize do
         @outstanding_sessions -= 1 if @outstanding_sessions.positive?
@@ -453,7 +982,23 @@ module Phronomy
     end
 
     def runtime_idle_locked?
-      @outstanding_sessions.zero? && @workflow_admissions.empty?
+      @outstanding_sessions.zero? &&
+        @agent_inflight_work.values.all?(&:empty?) &&
+        @agent_deferred_terminals.empty? &&
+        !workflow_admission_transition_in_progress_locked? &&
+        !agent_admission_transition_in_progress_locked?
+    end
+
+    def workflow_admission_transition_in_progress_locked?
+      @workflow_admissions.values.any? do |admission|
+        %i[admitting executing persisting_terminal].include?(admission.state)
+      end
+    end
+
+    def agent_admission_transition_in_progress_locked?
+      @agent_admissions.values.any? do |admission|
+        %i[admitting executing resuming cancelling terminalizing].include?(admission.state)
+      end
     end
 
     def join_until(deadline)
@@ -465,12 +1010,26 @@ module Phronomy
     end
 
     def finalize_terminated(status)
-      @lifecycle_mutex.synchronize do
+      pending_waiters = @lifecycle_mutex.synchronize do
+        waiters = @agent_completion_waiters.values.flatten
+        @agent_completion_waiters.clear
+        @agent_inflight_work.clear
+        @agent_deferred_terminals.clear
         @state = :terminated
-        @admitted_session_ids.clear
+        @admitted_fsm_session_ids.clear
         @workflow_admissions.clear
+        @agent_admissions.clear
+        @agent_executions.clear
         @thread = nil unless @thread&.alive?
         @idle_cond.broadcast
+        waiters
+      end
+      if pending_waiters.any?
+        error = Phronomy::ExecutionRehydrationRequiredError.new(
+          "Runtime terminated while Agent execution remained nonterminal; " \
+          "process-local Task handles are not rehydrated"
+        )
+        pending_waiters.each { |waiter| complete_waiter(waiter, error) }
       end
       status
     end