phronomy 0.11.0 → 0.11.1

data/lib/phronomy/engine/task/deferred_backend.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Phronomy
+  class Task
+    # Backend for externally-completed Tasks.
+    #
+    # DeferredBackend never starts a thread.  The owner transitions it to a
+    # terminal state by calling Task#transition! and then #unblock.
+    # @api private
+    class DeferredBackend < Backend
+      def initialize(task:, &)
+        super
+        @done_queue = Queue.new
+        task.transition!(:running)
+      end
+
+      # Unblocks await/join after the task reaches a terminal state.
+      # @api private
+      def unblock(value, error)
+        @done_queue.push([value, error])
+      end
+
+      # Blocks until externally completed.
+      # @api private
+      def wait_result
+        scheduler = Thread.current.thread_variable_get(Task::SCHEDULER_KEY)
+        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
+        if scheduler && in_managed_fiber && !@task.done?
+          scheduler.track_blocking_await
+          waiting_fiber = Fiber.current
+          @task.on_complete do |_value, _error|
+            scheduler.complete_blocking_await
+            scheduler.enqueue_fiber(-> { waiting_fiber.resume })
+          end
+          Fiber.yield(:cooperative_suspend)
+        end
+
+        value, error = @done_queue.pop
+        raise error if error
+
+        value
+      end
+
+      # Deferred tasks have no execution thread of their own.
+      # @api private
+      def alive?
+        !@task.done?
+      end
+
+      # Marks the task cancelled without interrupting external work.
+      # @api private
+      def cancel!
+        self
+      end
+
+      # Blocks until externally completed, with optional timeout.
+      # @api private
+      def join(limit = nil)
+        if limit.nil?
+          wait_result
+        else
+          begin
+            Timeout.timeout(limit) { wait_result }
+          rescue Timeout::Error
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -100,7 +100,7 @@ module Phronomy
       # @return [Object]
       # @raise [Exception]
       # @api private
-      def await
+      def wait_result
         unless @fiber.alive?
           raise @error if @error
           return @value

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

@@ -44,7 +44,7 @@ module Phronomy
       # @return [Object]
       # @raise [Exception]
       # @api private
-      def await
+      def wait_result
         raise @error if @error
 
         @value

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

@@ -37,7 +37,19 @@ module Phronomy
       # @return [Object] the mapped value
       # @raise [Exception] if the source task or the map block raised an error
       # @api private
-      def await
+      def wait_result
+        scheduler = Thread.current.thread_variable_get(Task::SCHEDULER_KEY)
+        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
+        if scheduler && in_managed_fiber && !@task.done?
+          scheduler.track_blocking_await
+          waiting_fiber = Fiber.current
+          @task.on_complete do |_value, _error|
+            scheduler.complete_blocking_await
+            scheduler.enqueue_fiber(-> { waiting_fiber.resume })
+          end
+          Fiber.yield(:cooperative_suspend)
+        end
+
         value, error = @done_queue.pop
         raise error if error
 
@@ -64,10 +76,10 @@ module Phronomy
       # @api private
       def join(limit = nil)
         if limit.nil?
-          await
+          wait_result
         else
           begin
-            Timeout.timeout(limit) { await }
+            Timeout.timeout(limit) { wait_result }
           rescue Timeout::Error
             nil
           end

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

@@ -41,7 +41,7 @@ module Phronomy
       # @return [Object]
       # @raise [Exception]
       # @api private
-      def await
+      def wait_result
         @thread.join
         raise @error if @error
 

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

@@ -5,6 +5,7 @@ require_relative "task/thread_backend"
 require_relative "task/immediate_backend"
 require_relative "task/fiber_backend"
 require_relative "task/mapped_backend"
+require_relative "task/deferred_backend"
 
 module Phronomy
   # A single unit of concurrent work.
@@ -21,7 +22,7 @@ module Phronomy
   #
   # @example Basic usage (framework/test code only — prefer Runtime.instance.spawn in app code)
   #   task = Phronomy::Task.spawn { expensive_io() }
-  #   result = task.await   # blocks until done, re-raises errors
+  #   result = task.wait_result   # blocks until done, re-raises errors
   #
   # @example Cancel a running task
   #   task = Phronomy::Task.spawn { loop { Phronomy::Task.checkpoint! } }
@@ -121,6 +122,15 @@ module Phronomy
       new(name: name, parent: parent, backend_class: backend_class, &block)
     end
 
+    # Creates a task whose lifecycle is completed externally.
+    # @param name [String, nil]
+    # @param parent [Task, nil]
+    # @return [Task]
+    # @api private
+    def self.deferred(name: nil, parent: current)
+      new(name: name, parent: parent, backend_class: DeferredBackend) {}
+    end
+
     # @return [String, nil] optional human-readable label
     attr_reader :name
 
@@ -161,8 +171,8 @@ module Phronomy
     # @return [Object] the result produced by the block
     # @raise [Exception] if the block raised an error
     # @api private
-    def await
-      @backend.await
+    def wait_result
+      @backend.wait_result
     end
 
     # Registers a callback to be invoked when the task reaches a terminal state
@@ -170,7 +180,7 @@ module Phronomy
     #
     # The callback receives two arguments: +value+ (the task's return value,
     # or +nil+) and +error+ (the exception, or +nil+).  These are provided
-    # directly so the callback does not need to call +task.await+, which would
+    # directly so the callback does not need to call +task.wait_result+, which would
     # risk a self-join error when the callback runs inside the task's own thread.
     #
     # If the task is already done when this method is called, the callback is
@@ -204,7 +214,7 @@ module Phronomy
     #
     # The primary use-case is transforming an agent result into a
     # {WorkflowContext} so that a Workflow entry action can return a Task
-    # whose value is picked up by {Workflow::FSMSession} via the existing
+    # whose value is picked up by {FSMSession} via the existing
     # +:action_completed+ path:
     #
     # @example Returning agent output into a Workflow state field
@@ -237,13 +247,15 @@ module Phronomy
             mapped_error = e
           end
         end
+        # Unblock mapped.wait_result / mapped.join before the terminal transition.
+        # on_complete callbacks may resume a waiting Fiber immediately; the
+        # queue must already contain the result at that point.
+        mapped.backend.unblock(mapped_value, mapped_error)
         if mapped_error
           mapped.transition!(:failed, error: mapped_error)
         else
           mapped.transition!(:completed, value: mapped_value)
         end
-        # Unblock mapped.await / mapped.join after the terminal transition.
-        mapped.backend.unblock(mapped_value, mapped_error)
       end
       mapped
     end

data/lib/phronomy/eval/scorer/llm_judge.rb

@@ -58,7 +58,7 @@ module Phronomy
         #     still returns 0.0 — warn is a side-effect not tested by value assertions
         def score(actual:, expected:, input: nil)
           prompt = format(@prompt_template, input: input.to_s, expected: expected.to_s, actual: actual.to_s)
-          response = Phronomy::Runtime.instance.blocking_io.submit { RubyLLM.chat(model: @model).ask(prompt) }.await
+          response = Phronomy::Runtime.instance.blocking_io.submit { RubyLLM.chat(model: @model).ask(prompt) }.blocking_wait
           response.content.to_s.strip.scan(/-?\d+\.?\d*/).first.to_f.clamp(0.0, 1.0)
         rescue => e
           raise if @raise_on_error

data/lib/phronomy/generator_verifier.rb

@@ -192,21 +192,30 @@ module Phronomy
         entry :draft, ->(state) {
           feedback = state.review_notes.last
           prompt = dpb.call(state.input, feedback)
-          result = draft_agent.invoke(prompt)
-          parsed = drp.call(result[:output])
-          state.draft = parsed[:answer].to_s
-          state.self_score = pipeline.__send__(:clamp, parsed[:confidence])
-          state.citations = pipeline.__send__(:normalize_citations, parsed[:citations])
-          state.iteration = state.iteration + 1
+          # Return a Task so WorkflowRunner awaits it off the EventLoop thread,
+          # then posts :action_completed with the new context back to EventLoop.
+          draft_agent.invoke_async(prompt).map do |result|
+            parsed = drp.call(result[:output])
+            state.merge(
+              draft: parsed[:answer].to_s,
+              self_score: pipeline.__send__(:clamp, parsed[:confidence]),
+              citations: pipeline.__send__(:normalize_citations, parsed[:citations]),
+              iteration: state.iteration + 1
+            )
+          end
         }
 
         entry :review, ->(state) {
           prompt = rpb.call(state.input, state.draft, state.citations)
-          result = review_agent.invoke(prompt)
-          parsed = rrp.call(result[:output])
-          state.review_score = pipeline.__send__(:clamp, parsed[:score])
-          state.approved = parsed[:approved] == true
-          state.review_notes << parsed[:feedback].to_s
+          # Return a Task so WorkflowRunner awaits it off the EventLoop thread.
+          review_agent.invoke_async(prompt).map do |result|
+            parsed = rrp.call(result[:output])
+            state.merge(
+              review_score: pipeline.__send__(:clamp, parsed[:score]),
+              approved: parsed[:approved] == true,
+              review_notes: [parsed[:feedback].to_s]
+            )
+          end
         }
 
         entry :finalize, ->(state) { state.output = state.draft }

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -84,7 +84,7 @@ module Phronomy
               input,
               thread_id: ctx[:thread_id] || parent_ic&.thread_id,
               config: task_config
-            ).await
+            ).wait_result
             result[:output]
           rescue
             raise if on_error == :raise
@@ -217,7 +217,7 @@ module Phronomy
           input,
           config: effective_config,
           thread_id: thread_id || ctx[:thread_id] || parent_ic&.thread_id
-        ).await
+        ).wait_result
       end
 
       private
@@ -306,7 +306,7 @@ module Phronomy
               task[:input],
               config: task_config,
               thread_id: task[:thread_id] || invocation_context&.thread_id
-            ).await
+            ).wait_result
           rescue => e
             errors[i] = e unless on_error == :skip
           end
@@ -324,7 +324,7 @@ module Phronomy
               "(#{alive.length} of #{spawned.length} tasks still running)"
           end
         else
-          spawned.each(&:await)
+          spawned.each(&:wait_result)
         end
 
         first_error = errors.compact.first

data/lib/phronomy/multi_agent/parallel_tool_chat.rb

@@ -77,7 +77,7 @@ module Phronomy
         # Thread that previously wrapped each pool operation.
         #
         # Both Phronomy::Task and BlockingAdapterPool::PendingOperation support
-        # #await, so results are collected uniformly below.
+        # #wait_result, so results are collected uniformly below.
         ct = @cancellation_token
         max = @max_parallel_tools
         tool_results = tool_calls.each_slice(max).flat_map do |batch|
@@ -105,7 +105,7 @@ module Phronomy
 
           # Await all dispatched operations in original order.
           dispatched.map do |item|
-            result = item[:awaitable] ? item[:awaitable].await : item[:result]
+            result = item[:awaitable] ? item[:awaitable].wait_result : item[:result]
             {tool_call: item[:tool_call], result: result}
           end
         end
@@ -142,7 +142,7 @@ module Phronomy
           tool: tool,
           args: tool_call.arguments,
           cancellation_token: @cancellation_token
-        ).await
+        ).wait_result
       end
     end
   end

data/lib/phronomy/tools/mcp.rb

@@ -158,7 +158,7 @@ module Phronomy
           @wait_thr = nil
           stderr_thread&.join(1)
           begin
-            stderr_op&.await(timeout: 1.0)
+            stderr_op&.blocking_wait(timeout: 1.0)
           rescue
             nil
           end

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.11.0"
+  VERSION = "0.11.1"
 end

data/lib/phronomy/workflow/phase_machine_builder.rb

@@ -170,11 +170,7 @@ module Phronomy
       # @api private
       def handle_entry_action_result(machine, result, state_name, timeout_secs)
         if result.is_a?(Phronomy::Task)
-          if Phronomy.configuration.event_loop
-            dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
-          else
-            await_task_blocking(machine, result, state_name, timeout_secs)
-          end
+          dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
         elsif result.is_a?(Phronomy::WorkflowContext)
           machine.context = result
         end
@@ -195,19 +191,34 @@ module Phronomy
       def dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
         machine.async_pending = true
         thread_id = machine.context.thread_id
-        Phronomy::Runtime.instance.spawn(name: "wf-await-#{thread_id}") do
-          enforce_timeout!(result, state_name, timeout_secs)
-          task_result = result.await
+        if timeout_secs
+          Phronomy::Runtime.instance.timer_queue.schedule(seconds: timeout_secs) do
+            next if result.done?
+
+            Phronomy::EventLoop.instance.post(
+              Phronomy::Event.new(
+                type: :error,
+                target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
+                payload: {session_id: thread_id, result: Phronomy::ActionTimeoutError.new(
+                  "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
+                )}
+              )
+            )
+          end
+        end
+        result.on_complete do |task_result, error|
+          if error
+            Phronomy::EventLoop.instance.post(
+              Phronomy::Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: thread_id, result: error})
+            )
+            next
+          end
           ev = if task_result.is_a?(Phronomy::WorkflowContext)
             Phronomy::Event.new(type: :action_completed, target_id: thread_id, payload: task_result)
           else
             Phronomy::Event.new(type: :state_completed, target_id: thread_id, payload: nil)
           end
           Phronomy::EventLoop.instance.post(ev)
-        rescue => e
-          Phronomy::EventLoop.instance.post(
-            Phronomy::Event.new(type: :error, target_id: thread_id, payload: e)
-          )
         end
       end
 
@@ -223,7 +234,7 @@ module Phronomy
       # @api private
       def await_task_blocking(machine, result, state_name, timeout_secs)
         enforce_timeout!(result, state_name, timeout_secs)
-        task_result = result.await
+        task_result = result.wait_result
         machine.context = task_result if task_result.is_a?(Phronomy::WorkflowContext)
       end
 

data/lib/phronomy/workflow.rb

@@ -96,6 +96,11 @@ module Phronomy
 
     # Invokes this workflow asynchronously and returns a {Phronomy::Task}.
     #
+    # Unlike {#invoke}, this method registers the workflow session with the
+    # EventLoop and returns immediately without spawning an extra OS thread.
+    # The returned Task resolves with the final context when the workflow
+    # finishes.
+    #
     # @param input  [Hash]
     # @param config [Hash]
     # @param invocation_context [Phronomy::InvocationContext, nil]
@@ -105,9 +110,7 @@ module Phronomy
       if invocation_context
         config = _apply_invocation_context(config, invocation_context)
       end
-      Phronomy::Runtime.instance.spawn(name: "workflow-invoke-async") do
-        invoke(input, config: config)
-      end
+      @runner.invoke_deferred(input, config: config)
     end
 
     # Resumes a halted workflow. Generic resume that works for all halt types.

data/lib/phronomy/workflow_context.rb

@@ -160,14 +160,16 @@ module Phronomy
     private
 
     # Asserts that the calling thread is allowed to mutate this context.
-    # No-op when EventLoop mode is disabled.
-    # @raise [Phronomy::WorkflowContextOwnershipError] when called from a
-    #   non-EventLoop thread in EventLoop mode.
+    # Raises WorkflowContextOwnershipError when called from outside the EventLoop
+    # dispatch thread, unless we are inside a synchronous execution context
+    # (e.g. Workflow#stream using the run_workflow sync path).
+    # @raise [Phronomy::WorkflowContextOwnershipError]
     # @api private
     # mutant:disable - multiple genuine equivalent mutations: defined?(Phronomy::EventLoop)&& removal is genuine because EventLoop is always loaded in the killfork environment; true&& is genuine (truthy guard); EventLoop.current? resolves to Phronomy::EventLoop.current? within the Phronomy module; WorkflowContextOwnershipError resolves to Phronomy::WorkflowContextOwnershipError within the module; raise without message or with nil message is genuine (spec checks exception class, not message text)
     def _assert_write_permitted!
-      return unless defined?(Phronomy::EventLoop) &&
-        Phronomy.configuration.event_loop
+      return unless defined?(Phronomy::EventLoop)
+      # Allow mutations when executing synchronously (e.g. Workflow#stream via run_workflow).
+      return if Thread.current[:phronomy_sync_execution]
       return if Phronomy::EventLoop.current?
 
       raise Phronomy::WorkflowContextOwnershipError,

data/lib/phronomy/workflow_runner.rb

@@ -79,29 +79,50 @@ module Phronomy
       caller_meta[:session_id] = config[:session_id] if config[:session_id]
 
       trace("workflow.invoke", input: input.inspect, **caller_meta) do |_span|
-        thread_id = config[:thread_id] || SecureRandom.uuid
-        recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
-
-        store = config.fetch(:state_store, @state_store) || Phronomy.configuration.state_store
-        snapshot = (store && config[:thread_id]) ? store.load(thread_id) : nil
-        initial_fields = if snapshot && snapshot[:fields]
-          snapshot[:fields].transform_keys(&:to_sym).merge(input.transform_keys(&:to_sym))
-        else
-          input
-        end
-
-        state = @state_class.new(**initial_fields)
-        state.set_graph_metadata(thread_id: thread_id)
-        result = if Phronomy.configuration.event_loop
-          run_via_event_loop(state, recursion_limit: recursion_limit)
-        else
-          run_workflow(state, recursion_limit: recursion_limit)
-        end
+        state, thread_id, recursion_limit, store = _build_initial_context(input, config)
+        result = run_via_event_loop(state, recursion_limit: recursion_limit)
         store&.save(thread_id, {fields: result.to_h, phase: result.phase.to_s}) if config[:thread_id]
         [result, nil]
       end
     end
 
+    # Registers the workflow with the EventLoop and returns a {Phronomy::Task}
+    # immediately without blocking the caller.  The task resolves with the final
+    # context when the workflow finishes.
+    #
+    # This is the EventLoop-driven equivalent of spawning a thread around
+    # {#invoke}.  No extra OS thread is created; the EventLoop's existing thread
+    # drives the execution.
+    #
+    # @param input [Hash] initial context field values
+    # @param config [Hash]
+    # @return [Phronomy::Task]
+    # @api private
+    def invoke_deferred(input, config: {})
+      state, thread_id, recursion_limit, store = _build_initial_context(input, config)
+      result_task = Phronomy::Task.deferred(name: "workflow-async:#{thread_id}")
+      Phronomy::EventLoop.instance.start
+      session = build_session_for(context: state, recursion_limit: recursion_limit)
+      if store && config[:thread_id]
+        # Wrap so that state is persisted when the task resolves.
+        persist_task = Phronomy::Task.deferred(name: "workflow-async-persist:#{thread_id}")
+        Phronomy::EventLoop.instance.register(session, completion: persist_task)
+        persist_task.on_complete do |result, error|
+          store.save(thread_id, {fields: result.to_h, phase: result.phase.to_s}) unless error
+          if error
+            result_task.backend.unblock(nil, error)
+            result_task.transition!(:failed, error: error)
+          else
+            result_task.backend.unblock(result, nil)
+            result_task.transition!(:completed, value: result)
+          end
+        end
+      else
+        Phronomy::EventLoop.instance.register(session, completion: result_task)
+      end
+      result_task
+    end
+
     # Generic resume. Equivalent to +send_event(state:, event: :resume, input:)+.
     # @param state [Object] halted context
     # @param input [Hash, nil] optional field updates to merge before resuming
@@ -142,13 +163,9 @@ module Phronomy
         event
       end
 
-      if Phronomy.configuration.event_loop
-        run_via_event_loop(state,
-          recursion_limit: Phronomy.configuration.recursion_limit,
-          resume_event: ev_to_fire, resume_phase: current_phase)
-      else
-        run_workflow(state, resume_event: ev_to_fire, resume_phase: current_phase)
-      end
+      run_via_event_loop(state,
+        recursion_limit: Phronomy.configuration.recursion_limit,
+        resume_event: ev_to_fire, resume_phase: current_phase)
     end
 
     # Streaming execution. Yields { state: Symbol, context: Object } after each state action completes.
@@ -167,9 +184,26 @@ module Phronomy
 
     private
 
+    # Builds the initial WorkflowContext from input and config.
+    # Returns [state, thread_id, recursion_limit, store].
+    def _build_initial_context(input, config)
+      thread_id = config[:thread_id] || SecureRandom.uuid
+      recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
+      store = config.fetch(:state_store, @state_store) || Phronomy.configuration.state_store
+      snapshot = (store && config[:thread_id]) ? store.load(thread_id) : nil
+      initial_fields = if snapshot && snapshot[:fields]
+        snapshot[:fields].transform_keys(&:to_sym).merge(input.transform_keys(&:to_sym))
+      else
+        input
+      end
+      state = @state_class.new(**initial_fields)
+      state.set_graph_metadata(thread_id: thread_id)
+      [state, thread_id, recursion_limit, store]
+    end
+
     # Builds an FSMSession for the given context. Used in EventLoop mode.
     def build_session_for(context:, recursion_limit:, resume_event: nil, resume_phase: nil)
-      Phronomy::Workflow::FSMSession.new(
+      Phronomy::FSMSession.new(
         id: context.thread_id,
         context: context,
         entry_point: @entry_point,
@@ -190,6 +224,9 @@ module Phronomy
     # Blocks the calling thread on a completion queue until the workflow
     # finishes, halts at a wait state, or raises an error.
     def run_via_event_loop(context, recursion_limit:, resume_event: nil, resume_phase: nil)
+      # Ensure EventLoop is running. In tests, reset_runtime! resets the
+      # singleton without restarting it; start is idempotent when already alive.
+      Phronomy::EventLoop.instance.start
       session = build_session_for(
         context: context, recursion_limit: recursion_limit,
         resume_event: resume_event, resume_phase: resume_phase
@@ -201,6 +238,19 @@ module Phronomy
     end
 
     def run_workflow(ctx, resume_event: nil, resume_phase: nil, recursion_limit: 25, &event_block)
+      # Mark the current thread as a synchronous execution context.
+      # This allows WorkflowContext field mutations via setters without raising
+      # WorkflowContextOwnershipError (which would otherwise fire since EventLoop
+      # is always active and run_workflow runs on the caller's thread).
+      Thread.current[:phronomy_sync_execution] = Thread.current[:phronomy_sync_execution].to_i + 1
+      _run_workflow_body(ctx, resume_event: resume_event, resume_phase: resume_phase,
+        recursion_limit: recursion_limit, &event_block)
+    ensure
+      depth = Thread.current[:phronomy_sync_execution].to_i - 1
+      Thread.current[:phronomy_sync_execution] = (depth > 0) ? depth : nil
+    end
+
+    def _run_workflow_body(ctx, resume_event: nil, resume_phase: nil, recursion_limit: 25, &event_block)
       if resume_event
         # -- Resume from a wait state -------------------------------------------
         # Fire the external event on a tracker positioned at the wait state.
@@ -231,7 +281,7 @@ module Phronomy
                   "Action in state #{current_state.inspect} timed out after #{timeout_secs}s"
               end
             end
-            task_result = result.await
+            task_result = result.wait_result
             ctx = task_result if task_result.is_a?(Phronomy::WorkflowContext)
           elsif result.is_a?(Phronomy::WorkflowContext)
             ctx = result

data/lib/phronomy.rb

@@ -11,11 +11,18 @@ loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
 # RAG: Zeitwerk would infer "Rag" — override to "RAG".
 loader.inflector.inflect("rag" => "RAG")
 # FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
+# Phronomy::FSMSession is the top-level cooperative execution engine shared by
+# WorkflowRunner and Agent::InvocationSession.
 loader.inflector.inflect("fsm_session" => "FSMSession")
 # LLMAdapter: Zeitwerk would infer "LlmAdapter" — override to "LLMAdapter".
 loader.inflector.inflect("llm_adapter" => "LLMAdapter")
 # LLMAdapter::RubyLLM: "ruby_llm" maps to "RubyLLM" (not "RubyLlm").
 loader.inflector.inflect("ruby_llm" => "RubyLLM")
+# Collapse engine/ so that its contents autoload directly under Phronomy::
+# (no Engine:: prefix).  e.g. engine/event_loop.rb => Phronomy::EventLoop.
+# This allows the execution engine to be organised in its own subdirectory
+# without changing any class names or callers.
+loader.collapse("#{__dir__}/phronomy/engine")
 loader.setup
 
 require_relative "phronomy/version"
@@ -99,14 +106,6 @@ module Phronomy
     end
   end
 
-  # Raised when {Agent::Base#resume} (or the class-level equivalent) is called
-  # with a {Agent::Checkpoint} whose +checkpoint_id+ has already been consumed
-  # by a previous +resume+ call on the same store.
-  #
-  # This protects against duplicate resume executions caused by webhook retries
-  # or queue message redelivery.
-  class CheckpointAlreadyResumedError < Error; end
-
   # Raised when an operation is submitted to a {BlockingAdapterPool} that has
   # already been shut down via {BlockingAdapterPool#shutdown}.
   class PoolShutdownError < Error; end
@@ -187,8 +186,17 @@ module Phronomy
     #   config.around { |ex| Phronomy.reset_runtime! ; ex.run ; Phronomy.reset_runtime! }
     # @api public
     def reset_runtime!
-      Phronomy::EventLoop.reset!
+      # Do NOT stop the EventLoop here. Since Phase 2, all Agent#invoke calls
+      # go through FSMSession + EventLoop. Stopping and restarting the EventLoop
+      # on every after(:each) hook would add thread creation overhead per test.
+      # run_via_event_loop and _invoke_via_fsm restart it lazily if it was reset.
+      #
+      # Preserve event_loop_stop_grace_seconds from the current configuration
+      # so that test suites that set it to 0 (for fast teardown) keep that value
+      # across configuration resets.
+      prev_grace = @configuration&.event_loop_stop_grace_seconds
       @configuration = Configuration.new
+      @configuration.event_loop_stop_grace_seconds = prev_grace if prev_grace
     end
   end
 end