phronomy 0.11.0 → 0.12.0

data/lib/phronomy/{concurrency → engine/concurrency}/async_queue.rb

@@ -20,6 +20,9 @@ module Phronomy
       def initialize(max_size: nil)
         @queue = max_size ? SizedQueue.new(max_size) : Thread::Queue.new
         @max_size = max_size
+        @waiter_mutex = Mutex.new
+        @cross_thread_waiter = nil    # [fiber, scheduler] set by _pop_cooperative; consumed by push
+        @cross_thread_scheduler = nil # set by expect_cross_thread_push
       end
 
       # Enqueues +item+.
@@ -37,6 +40,24 @@ module Phronomy
         else
           @queue.push(item)
           scheduler.raise_signal(@coop_signal) if scheduler && @coop_signal
+          # Wake a cross-thread waiter if one is registered.
+          # Handles the case where a DeterministicScheduler Fiber is suspended
+          # in _pop_cooperative waiting for a push from a non-scheduler thread
+          # (e.g. EventLoop thread where Scheduler.current is nil).
+          # enqueue_fiber is thread-safe; complete_blocking_await decrements
+          # @pending_awaits so run_until_idle can eventually exit.
+          if @cross_thread_scheduler
+            waiter = @waiter_mutex.synchronize do
+              w = @cross_thread_waiter
+              @cross_thread_waiter = nil
+              w
+            end
+            if waiter
+              fiber, sched = waiter
+              sched.complete_blocking_await
+              sched.enqueue_fiber(-> { fiber.resume })
+            end
+          end
         end
         self
       end
@@ -103,14 +124,37 @@ module Phronomy
         self
       end
 
+      # Marks this queue as expecting pushes from a non-scheduler OS thread.
+      # When set, {#pop} in cooperative mode uses +track_blocking_await+ so that
+      # {Runtime::DeterministicScheduler#run_until_idle} does not exit while
+      # waiting for the cross-thread push.  Called by {EventLoop#register} when
+      # a cooperative scheduler is active on the calling thread.
+      # @param scheduler [Runtime::Scheduler]
+      # @return [self]
+      # @api private
+      def expect_cross_thread_push(scheduler)
+        @cross_thread_scheduler = scheduler
+        self
+      end
+
       private
 
       # Cooperative pop for DeterministicScheduler context.
       # Suspends the current Fiber via the scheduler's signal mechanism rather than
-      # blocking the OS thread.  Because cooperative mode is single-threaded, the
-      # empty?/pop pair is race-free (no other Fiber can run between the two calls).
-      # After dequeuing, notifies any push-waiter so that a backpressure-suspended
-      # producer can be unblocked.
+      # blocking the OS thread.
+      #
+      # Two suspension paths:
+      # * **Same-scheduler** (default): uses {CoopSignal} — the producer is another
+      #   Fiber on the same DeterministicScheduler.  run_until_idle is allowed to
+      #   exit; the producer's push will enqueue the consumer Fiber.
+      # * **Cross-thread** ({#expect_cross_thread_push} was called): uses
+      #   +track_blocking_await+ so that run_until_idle does not exit while waiting
+      #   for a push from a non-scheduler OS thread (e.g. EventLoop).  The push
+      #   side calls +complete_blocking_await+ + +enqueue_fiber+ to resume.
+      #
+      # The empty?/register pair for the cross-thread path is wrapped in
+      # @waiter_mutex to eliminate the race between the empty check and the
+      # registration of the waker.
       # @api private
       # @param scheduler [Runtime::Scheduler]
       # @param timeout [Numeric, nil]
@@ -127,7 +171,26 @@ module Phronomy
             return item
           end
           return nil if deadline && scheduler.virtual_time >= deadline
-          scheduler.wait_for_signal(@coop_signal)
+
+          if @cross_thread_scheduler
+            # Cross-thread path: atomically check the queue and register a waker
+            # so that a concurrent push cannot slip between the empty? check above
+            # and the registration below.
+            will_yield = false
+            @waiter_mutex.synchronize do
+              if @queue.empty?
+                @cross_thread_waiter = [Fiber.current, scheduler]
+                scheduler.track_blocking_await
+                will_yield = true
+              end
+              # else: push arrived between the loop's empty? check and here;
+              # will_yield stays false and the next loop iteration dequeues it.
+            end
+            Fiber.yield(:cooperative_suspend) if will_yield
+          else
+            scheduler.wait_for_signal(@coop_signal)
+          end
+
           return nil if deadline && scheduler.virtual_time >= deadline
         end
       end

data/lib/phronomy/{concurrency → engine/concurrency}/blocking_adapter_pool.rb

@@ -26,12 +26,12 @@ module Phronomy
     #
     # @example Submitting a blocking LLM call
     #   op = runtime.blocking_io.submit(timeout: 30) { chat.ask(message) }
-    #   result = op.await   # blocks the calling thread until done
+    #   result = op.blocking_wait   # blocks the calling thread until done
     #
     # @example With cancellation
     #   token = Phronomy::Concurrency::CancellationToken.timeout_after(60)
     #   op = pool.submit(timeout: 30, cancellation_token: token) { expensive_call }
-    #   result = op.await
+    #   result = op.blocking_wait
     class BlockingAdapterPool
       # Represents the pending result of a submitted blocking operation.
       # Returned immediately by {BlockingAdapterPool#submit}; call {#await} to
@@ -103,7 +103,7 @@ module Phronomy
         # @raise [Phronomy::CancellationError]
         # @raise [Exception] error raised inside the submitted block
         # @api private
-        def await(timeout: nil, cancellation_token: nil)
+        def blocking_wait(timeout: nil, cancellation_token: nil)
           effective_timeout = [timeout, @timeout].compact.min
           effective_token = cancellation_token || @cancellation_token
 
@@ -174,6 +174,12 @@ module Phronomy
           @value
         end
 
+        # Unified wait interface compatible with {Phronomy::Task#wait_result}.
+        # Delegates to {#blocking_wait} so that callers treating the return value
+        # of {ToolExecutor.call_async} uniformly as +#wait_result+ work correctly
+        # regardless of whether a Task or PendingOperation is returned.
+        alias_method :wait_result, :blocking_wait
+
         # Registers a callback to be called when the operation finishes.
         # If the operation has already finished the callback is invoked immediately
         # on the calling thread.  Otherwise it is invoked on the worker thread that

data/lib/phronomy/{event_loop.rb → engine/event_loop.rb}

@@ -9,7 +9,7 @@ module Phronomy
   # +BlockingAdapterPool+, then post results back to the loop via
   # {EventLoop#post}.
   #
-  # Activated with: +Phronomy.configure { |c| c.event_loop = true }+
+  # Always active — all Workflow and Agent invocations use the EventLoop.
   #
   # == Threading exception (see ADR-010 Rule 2)
   #
@@ -49,6 +49,11 @@ module Phronomy
   # +Runtime.instance.spawn+ or +BlockingAdapterPool+, then post events back
   # via +Phronomy::EventLoop.instance.post(...)+.
   class EventLoop
+    # Sentinel target_id for EventLoop management events (:start, :finished, :halted, :error).
+    # Events with this target_id are processed directly by the EventLoop and never
+    # routed to any FSMSession via handle(event).
+    SYSTEM_CHANNEL_ID = "__event_loop__"
+
     # Returns the singleton instance, creating and starting it on first call.
     def self.instance
       @instance ||= new.tap(&:start)
@@ -129,11 +134,11 @@ module Phronomy
     # (WorkflowContext) once the workflow finishes or halts. If an error occurred,
     # the popped value will be an Exception — callers are responsible for re-raising it.
     #
-    # @param fsm_session [Phronomy::Workflow::FSMSession]
+    # @param fsm_session [Phronomy::FSMSession]
     # @return [Phronomy::Concurrency::AsyncQueue] resolves to final/halted context, or an Exception
     # @api private
-    def register(fsm_session)
-      if Phronomy::EventLoop.current?
+    def register(fsm_session, completion: nil)
+      if Phronomy::EventLoop.current? && !completion.is_a?(Phronomy::Task)
         raise Phronomy::Error,
           "Cannot call Workflow#invoke (EventLoop mode) from within an EventLoop " \
           "entry action. Schedule work via Runtime.instance.spawn or " \
@@ -141,10 +146,17 @@ module Phronomy
           "Phronomy::EventLoop.instance.post(...) instead."
       end
 
-      completion_queue = Phronomy::Concurrency::AsyncQueue.new
+      completion_queue = completion || Phronomy::Concurrency::AsyncQueue.new
+      # When called from a DeterministicScheduler Fiber (e.g. :fiber backend),
+      # mark the queue so that _pop_cooperative uses track_blocking_await.
+      # This prevents run_until_idle from exiting before the EventLoop thread
+      # (a different OS thread where Scheduler.current is nil) pushes the result.
+      scheduler = Phronomy::Runtime::Scheduler.current
+      completion_queue.expect_cross_thread_push(scheduler) if scheduler && completion_queue.respond_to?(:expect_cross_thread_push)
       # Pass both session and completion_queue in the event payload so that the
       # EventLoop thread is the sole writer of @fsms and @waiting.
-      @queue.push([Event.new(type: :start, target_id: fsm_session.id,
+      # Use SYSTEM_CHANNEL_ID so the management event is never routed to an FSM.
+      @queue.push([Event.new(type: :start, target_id: SYSTEM_CHANNEL_ID,
         payload: {session: fsm_session, completion: completion_queue}),
         Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)])
       completion_queue
@@ -282,40 +294,46 @@ module Phronomy
         check_starvation_lag(lag_ns, event)
 
         dispatch_start_ns = dequeued_at_ns
-        case event.type
-        when :finished, :halted, :error
-          # All three terminal events share the same cleanup path.
-          # Both @fsms and @waiting are exclusively owned by this thread.
-          @fsms.delete(event.target_id)
-          cq = @waiting.delete(event.target_id)
-          cq&.push(event.payload)
-          # Decrement active FSM count and signal drain waiters.
-          @fsm_count_mutex.synchronize do
-            @fsm_count -= 1
-            @fsm_count_cond.signal if @fsm_count <= 0
-          end
+        if event.target_id == SYSTEM_CHANNEL_ID
+          # Management channel: lifecycle events processed directly by EventLoop.
+          # Never routed to any FSMSession.
+          case event.type
+          when :finished, :halted, :error
+            # session_id is carried in the payload so the FSM can use its own ID
+            # as the FSM-facing target_id for other events.
+            session_id = event.payload[:session_id]
+            @fsms.delete(session_id)
+            cq = @waiting.delete(session_id)
+            complete_waiter(cq, event.payload[:result])
+            # Decrement active FSM count and signal drain waiters.
+            @fsm_count_mutex.synchronize do
+              @fsm_count -= 1
+              @fsm_count_cond.signal if @fsm_count <= 0
+            end
 
-        when :start
-          # session and completion_queue arrive together in the payload so that
-          # this thread is the sole writer of @fsms and @waiting.
-          # completion may be nil for fire-and-forget child sessions (AgentFSM).
-          session = event.payload[:session]
-          cq = event.payload[:completion]
-
-          # When shutdown has been requested, reject new sessions with a
-          # CancellationError rather than starting new LLM calls that would
-          # be interrupted by force-kill.
-          if @shutdown_token.cancelled? && cq
-            cq.push(Phronomy::CancellationError.new("EventLoop is shutting down"))
-            next
-          end
+          when :start
+            # session and completion_queue arrive together in the payload so that
+            # this thread is the sole writer of @fsms and @waiting.
+            # completion may be nil for fire-and-forget child sessions (AgentFSM).
+            session = event.payload[:session]
+            cq = event.payload[:completion]
 
-          @fsms[event.target_id] = session
-          @waiting[event.target_id] = cq if cq
-          @fsm_count_mutex.synchronize { @fsm_count += 1 }
-          session.start
+            # When shutdown has been requested, reject new sessions with a
+            # CancellationError rather than starting new LLM calls that would
+            # be interrupted by force-kill.
+            if @shutdown_token.cancelled? && cq
+              complete_waiter(cq, Phronomy::CancellationError.new("EventLoop is shutting down"))
+              next
+            end
+
+            @fsms[session.id] = session
+            @waiting[session.id] = cq if cq
+            @fsm_count_mutex.synchronize { @fsm_count += 1 }
+            session.start
+          end
 
         else
+          # FSM channel: route to the target FSMSession by target_id.
           fsm = @fsms[event.target_id]
           if fsm
             fsm.handle(event)
@@ -332,10 +350,26 @@ module Phronomy
       end
     rescue => e
       # Unblock all waiting callers if the loop dies unexpectedly.
-      @waiting.values.each { |cq| cq.push(e) }
+      @waiting.values.each { |cq| complete_waiter(cq, e) }
       raise
     end
 
+    def complete_waiter(waiter, payload)
+      return unless waiter
+
+      if waiter.is_a?(Phronomy::Task)
+        if payload.is_a?(Exception)
+          waiter.backend.unblock(nil, payload)
+          waiter.transition!(:failed, error: payload)
+        else
+          waiter.backend.unblock(payload, nil)
+          waiter.transition!(:completed, value: payload)
+        end
+      else
+        waiter.push(payload)
+      end
+    end
+
     def update_lag_metrics(lag_ns)
       @lag_mutex.synchronize do
         @last_lag_ns = lag_ns

data/lib/phronomy/engine/fsm_session.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Event-driven execution wrapper for a single FSM session.
+  #
+  # Used by both WorkflowRunner (for Workflow) and Agent::InvocationSession
+  # (for Agent invoke). Not Workflow-specific.
+  #
+  # Created by a runner and registered with EventLoop. All public methods
+  # are called from the EventLoop thread — FSMSession is NOT thread-safe and must
+  # not be accessed concurrently from multiple threads.
+  #
+  class FSMSession
+    FINISH = WorkflowRunner::FINISH
+
+    # @return [String] workflow thread_id (matches WorkflowContext#thread_id)
+    attr_reader :id
+
+    # @param id                  [String]
+    # @param context             [Object]        includes Phronomy::WorkflowContext
+    # @param entry_point         [Symbol]        initial state name
+    # @param entry_actions       [Hash]          { state_name => [callable, ...] }
+    # @param auto_state_set      [Hash]          { state_name => true }
+    # @param declared_states     [Array<Symbol>] all action state names
+    # @param wait_state_names    [Array<Symbol>]
+    # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
+    # @param phase_machine_class [Class]         state_machines-backed phase tracker class
+    # @param recursion_limit     [Integer]
+    # @param action_timeouts     [Hash]          { state_name => seconds }
+    # @param resume_event        [Symbol, nil]   external event to fire when resuming
+    # @param resume_phase        [Symbol, nil]   wait state name to resume from
+    # @api private
+    def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
+      declared_states:, wait_state_names:, external_events:, phase_machine_class:,
+      recursion_limit:, action_timeouts: {}, resume_event: nil, resume_phase: nil)
+      @id = id
+      @ctx = context
+      @entry_point = entry_point
+      @entry_actions = entry_actions
+      @auto_state_set = auto_state_set
+      @declared_states = declared_states
+      @wait_state_names = wait_state_names
+      @external_events = external_events
+      @phase_machine_class = phase_machine_class
+      @recursion_limit = recursion_limit
+      @action_timeouts = action_timeouts
+      @resume_event = resume_event
+      @resume_phase = resume_phase
+      @step = 0
+      @done = false
+      @current_state = nil
+      @tracker = nil
+    end
+
+    # Begins workflow execution. Called by EventLoop on :start event.
+    def start
+      if @resume_event
+        # Resume from wait state: position tracker at the wait state, then fire the
+        # external event. state_machines fires before_transition (exit) and
+        # after_transition (entry) callbacks, so both actions execute here.
+        @current_state = @resume_phase
+        @tracker = build_tracker(@current_state)
+        @tracker.context = @ctx
+        @tracker.session_id = @id if @tracker.respond_to?(:session_id=)
+        fire_and_advance!(@resume_event)
+      else
+        # Fresh start: state_machines does not fire callbacks on initialization,
+        # so we invoke the entry action for the initial state manually.
+        @current_state = @entry_point
+        @tracker = build_tracker(@current_state)
+        @tracker.context = @ctx
+        @tracker.session_id = @id if @tracker.respond_to?(:session_id=)
+        (@entry_actions[@current_state] || []).each do |c|
+          result = c.call(@ctx)
+          if result.is_a?(Phronomy::Task)
+            # Awaitable action: resume via on_complete without blocking EventLoop.
+            @tracker.async_pending = true
+            session_id = @id
+            current_state_name = @current_state
+            timeout_secs = @action_timeouts[current_state_name]
+            if timeout_secs
+              Phronomy::Runtime.instance.timer_queue.schedule(seconds: timeout_secs) do
+                next if result.done?
+
+                event_loop.post(
+                  Event.new(
+                    type: :error,
+                    target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
+                    payload: {session_id: session_id, result: Phronomy::ActionTimeoutError.new(
+                      "Action in state #{current_state_name.inspect} timed out after #{timeout_secs}s"
+                    )}
+                  )
+                )
+              end
+            end
+            result.on_complete do |task_result, error|
+              if error
+                event_loop.post(Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: session_id, result: error}))
+                next
+              end
+              if _fsm_context?(task_result)
+                event_loop.post(Event.new(type: :action_completed, target_id: session_id, payload: task_result))
+              else
+                event_loop.post(Event.new(type: :state_completed, target_id: session_id, payload: nil))
+              end
+            end
+            break # Only one async action at a time per state
+          elsif _fsm_context?(result)
+            @ctx = result
+          end
+        end
+        @tracker.context = @ctx
+        advance_or_halt unless @tracker.async_pending
+      end
+    rescue => e
+      finish_with_error(e)
+    end
+
+    # Processes an event dispatched from EventLoop.
+    # Called for :state_completed, :action_completed, and all user-defined external events.
+    #
+    # @param event [Phronomy::Event]
+    # @api private
+    def handle(event)
+      return if @done
+
+      if event.type == :action_completed
+        # An awaitable entry action completed: update context and advance.
+        @ctx = event.payload if _fsm_context?(event.payload)
+        @tracker.context = @ctx
+        @tracker.async_pending = false  # Reset flag set by start or fire_and_advance!
+        advance_or_halt
+        return
+      end
+
+      # When :state_completed arrives from an async Task (non-WorkflowContext result),
+      # async_pending may still be true from the spawn. Clear it before advancing.
+      @tracker.async_pending = false if event.type == :state_completed && @tracker.async_pending
+
+      fire_and_advance!(event.type)
+    rescue => e
+      finish_with_error(e)
+    end
+
+    private
+
+    # Fires event_name on the phase tracker, updates @current_state, then
+    # calls advance_or_halt to decide what to do next.
+    def fire_and_advance!(event_name)
+      if @step >= @recursion_limit
+        raise Phronomy::RecursionLimitError,
+          "Recursion limit (#{@recursion_limit}) exceeded"
+      end
+
+      fire_event!(@tracker, event_name, @current_state)
+      @ctx = @tracker.context
+      next_phase = @tracker.phase.to_sym
+      # When next_phase == @current_state, no transition matched → treat as terminal.
+      @current_state = (next_phase == @current_state) ? FINISH : next_phase
+      @step += 1
+
+      # If an entry action returned a Task, the after_transition callback set
+      # async_pending = true and spawned a thread. Skip advance_or_halt — the
+      # background thread will post :action_completed or :state_completed.
+      if @tracker.async_pending
+        @tracker.async_pending = false
+        return
+      end
+
+      advance_or_halt
+    end
+
+    # Determines the next action after the FSM has entered @current_state.
+    def advance_or_halt
+      return finish! if @current_state == FINISH
+
+      if @wait_state_names.include?(@current_state)
+        return halt!
+      end
+
+      if @auto_state_set.key?(@current_state)
+        event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
+        return
+      end
+
+      if has_external_event_from?(@current_state)
+        # Async IO pattern: the entry action spawned an IO thread that will post
+        # an external event back. Stay registered; do nothing here.
+        return
+      end
+
+      # No transition declared — validate the state is known, then treat as terminal.
+      unless @declared_states.include?(@current_state)
+        raise ArgumentError, "State #{@current_state.inspect} is not defined"
+      end
+
+      finish!
+    end
+
+    def finish!
+      @done = true
+      @ctx.set_graph_metadata(thread_id: @id, phase: :__end__)
+      event_loop.post(Event.new(type: :finished, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: @ctx}))
+    end
+
+    def halt!
+      @done = true
+      @ctx.set_graph_metadata(thread_id: @id, phase: @current_state)
+      event_loop.post(Event.new(type: :halted, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: @ctx}))
+    end
+
+    def finish_with_error(err)
+      @done = true
+      event_loop.post(Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: @id, result: err}))
+    end
+
+    def fire_event!(tracker, event_name, from_state)
+      return if tracker.send(event_name)
+
+      raise ArgumentError,
+        "Transition from #{from_state.inspect} via event #{event_name.inspect} failed. " \
+        "Ensure at least one guard matches or add a fallback (no-guard) transition."
+    end
+
+    def has_external_event_from?(state)
+      @external_events.any? { |_, transitions| transitions.any? { |t| t[:from] == state } }
+    end
+
+    def build_tracker(from_state)
+      machine = @phase_machine_class.new
+      machine.instance_variable_set(:@phase, from_state.to_s)
+      machine
+    end
+
+    def event_loop
+      Phronomy::EventLoop.instance
+    end
+
+    # Returns true when +obj+ is an FSM execution context (responds to
+    # +set_graph_metadata+). Used to distinguish context objects from other
+    # Task return values (strings, hashes, etc.) without hard-coding a specific
+    # class. Both WorkflowContext and Agent::InvocationContext qualify.
+    # @api private
+    def _fsm_context?(obj)
+      obj.respond_to?(:set_graph_metadata)
+    end
+  end
+end

data/lib/phronomy/{runtime → engine/runtime}/deterministic_scheduler.rb

@@ -99,6 +99,13 @@ module Phronomy
         @pending_awaits = 0
         @await_mutex = Mutex.new
         @await_cond = ConditionVariable.new
+        # Tracks which OS thread is currently executing run_until_idle.
+        # When a spawn is called from a DIFFERENT thread while run_until_idle is
+        # active, creating a FiberBackend on that thread would produce a Fiber
+        # that the run_until_idle owner thread cannot resume (Ruby 3+ restriction).
+        # The mutex is separate from @mutex/@await_mutex to avoid lock-ordering issues.
+        @rui_mutex = Mutex.new
+        @run_until_idle_thread = nil
       end
 
       # Returns +true+ when this scheduler is in autorun mode.
@@ -116,6 +123,23 @@ module Phronomy
       # @return [Task]
       # @api private
       def spawn(name:, parent:, &block)
+        inside_tick = Thread.current.thread_variable_get(SCHEDULER_KEY)
+        rui_thread = @rui_mutex.synchronize { @run_until_idle_thread }
+
+        # Cross-thread guard: if run_until_idle is active on a DIFFERENT OS thread
+        # (e.g. the EventLoop calling Runtime.instance.spawn while the test thread
+        # is blocked in run_until_idle waiting for a cross-thread push), creating a
+        # FiberBackend here would produce a Fiber owned by THIS thread.  The
+        # run_until_idle owner thread cannot resume it, which raises:
+        #   FiberError: fiber called across threads
+        # Fall back to ThreadBackend so the block runs on its own OS thread instead,
+        # and broadcast @await_cond so the owner thread is notified of new work.
+        if !inside_tick && rui_thread && rui_thread != Thread.current
+          task = Task.spawn(name: name, parent: parent, backend_class: Task::ThreadBackend, &block)
+          @await_mutex.synchronize { @await_cond.broadcast }
+          return task
+        end
+
         task = Task.spawn(name: name, parent: parent, backend_class: Task::FiberBackend, &block)
         backend = task.backend
         # Build a self-rescheduling step: after each step, re-enqueue if the
@@ -130,7 +154,7 @@ module Phronomy
         # When SCHEDULER_KEY is set, the calling code is already inside a managed
         # Fiber; the outer run_until_idle loop will pick up the new task on the
         # next iteration without a recursive re-entry.
-        run_until_idle if @autorun && Thread.current.thread_variable_get(SCHEDULER_KEY).nil?
+        run_until_idle if @autorun && !inside_tick
         task
       end
 
@@ -202,6 +226,7 @@ module Phronomy
       # @return [self]
       # @api private
       def run_until_idle
+        @rui_mutex.synchronize { @run_until_idle_thread = Thread.current }
         if @autorun
           loop do
             fire_real_timers
@@ -230,6 +255,8 @@ module Phronomy
           tick until idle?
         end
         self
+      ensure
+        @rui_mutex.synchronize { @run_until_idle_thread = nil }
       end
 
       # Advances the virtual clock by +seconds+ and enqueues any timer

data/lib/phronomy/{runtime → engine/runtime}/fake_scheduler.rb

@@ -30,7 +30,7 @@ module Phronomy
     # @example
     #   runtime = Phronomy::Runtime.new(scheduler: Phronomy::Runtime::FakeScheduler.new)
     #   task = runtime.spawn(name: "agent-test") { 42 }
-    #   expect(task.await).to eq(42)
+    #   expect(task.wait_result).to eq(42)
     #   expect(task.status).to eq(:completed)
     # @api private
     class FakeScheduler < Scheduler

data/lib/phronomy/{runtime.rb → engine/runtime.rb}

@@ -32,7 +32,7 @@ module Phronomy
   # @example Test usage — no extra threads
   #   runtime = Phronomy::Runtime.new(scheduler: Phronomy::Runtime::FakeScheduler.new)
   #   task = runtime.spawn { 42 }
-  #   expect(task.await).to eq(42)
+  #   expect(task.wait_result).to eq(42)
   class Runtime
     # Returns the process-wide default Runtime.
     #
@@ -366,9 +366,7 @@ module Phronomy
       @task_registry.drain
       # Drain EventLoop events before stopping pools so that in-flight
       # Workflow / Agent FSM sessions can complete their final LLM calls.
-      if Phronomy.configuration.event_loop
-        Phronomy::EventLoop.instance.stop(drain: true)
-      end
+      Phronomy::EventLoop.instance.stop(drain: true)
       @pool_registry.shutdown
       @timer_service.shutdown
     end

data/lib/phronomy/{task → engine/task}/backend.rb

@@ -24,8 +24,8 @@ module Phronomy
       # @return [Object]
       # @raise [Exception]
       # @api private
-      def await
-        raise NotImplementedError, "#{self.class}#await not implemented"
+      def wait_result
+        raise NotImplementedError, "#{self.class}#wait_result not implemented"
       end
 
       # Returns +true+ while execution is still ongoing.