phronomy 0.30.1 → 0.32.0

data/docs/runtime-and-concurrency.md

@@ -668,6 +668,165 @@ imply durable Agent continuation reconstruction.
 `Phronomy.reset_runtime!` exists primarily for test isolation and performs a real
 Runtime shutdown before resetting configuration.
 
+## Hosting a standalone Agent through approval
+
+A host can release one suspended Agent and continue using its Ruby process for other Agents. Hold one external claim per mutable Agent while loading, executing, detaching and recording delivery. Persist a new request's reserved execution ID before dispatch. A host uses the existing incarnation-level listener to receive the approval request.
+
+For example, worker A starts a fresh reservation with `agent.start_hosted(reservation:, input:)`. If the run finishes directly, `handle.wait_result` returns the ordinary execution result. On an approval notification, call `handle.detach!(approval_request_id: request.id)` outside EventLoop. Success returns an immutable `ApprovalWait` with the execution ID, approval request ID and committed revision. The same handle then returns that wait. The released Agent object cannot be reused. Existing `invoke_async` handles keep their terminal-result contract.
+
+An incorrect or stale approval, outstanding physical work, concurrent operation, live scope or durable retention prevents transfer. A busy response leaves the host responsible for the claim. A spent reservation is rejected. After a verified worker exit, a host can query `store.standalone_approval_wait(agent_id:, execution_id:)` without loading the Agent. A missing or ineligible wait returns nil. Store errors and owner mismatches propagate. Only reclaim a delivery if the original worker is known to have stopped and its claim still matches.
+
+Worker B loads the Agent with an `on_event:` listener, checks the restored request against the accepted answer and calls `approve` with the execution and approval request IDs. The host owns input deduplication and result acknowledgement. For a direct subagent, use the parent's hosted handle as described below.
+
+## Hosting an Orchestrator through a child approval
+
+A hosted Orchestrator can release its local Agent and one direct subagent when
+the subagent is waiting for Tool approval. The parent execution has one reserved
+child slot and its current Tool batch contains only the dispatch for that slot.
+The host holds exclusive access to both Agents throughout the handoff. It
+delivers work to the next worker only after release succeeds.
+
+For example, worker A starts a parent with `start_hosted`. Its listener receives
+the child's approval request. A host thread outside EventLoop passes the IDs
+from that request to the parent handle.
+
+```ruby
+wait = handle.detach!(execution_id: request.execution_id, approval_request_id: request.id)
+```
+
+The returned `Agent::ApprovalWait` identifies the child execution, its approval
+request and its saved revision. Keep the parent Agent and execution IDs with the
+accepted request. Both old Agent objects reject later execution operations.
+Worker A can keep unrelated Agent instances and process another request.
+The parent's original result handle retains its
+`ExecutionRehydrationRequiredError` outcome at this boundary.
+
+Worker B loads the same parent class with its Agent Store, coordination Store
+and listener. `parent.resume_async(parent_execution_id)` restores the pending
+child and emits the same approval request. Compare its execution and request
+IDs with the accepted request. The parent attempt reports
+`ExecutionRehydrationRequiredError` while the child is waiting. Obtain the
+restored child from its registered class by child Agent ID, call
+`child.approve(child_execution_id, approval_request_id:, approved:)`, then
+`parent.resume(parent_execution_id)` to import the result. A rejection is a
+child outcome. The parent continues according to its own dispatch and Agent
+logic.
+
+If the child may need another handoff, the host answers the current approval
+through the restored parent on a host thread outside EventLoop. This returns a
+hosted handle for the child's operation. If the child finishes, the handle
+yields the child result and the parent can import it. If the child requests
+another approval, the host can use the handle to release the same pair.
+
+For example, B approves the child's `apply_request` and the same child execution
+then asks to call `publish_request`. B uses the first approval's ID to answer and
+the second approval's ID to detach. The queue below receives the child approval
+events from the listener installed when B loaded the parent. This fixture
+requests a second approval within its test timeout.
+
+```ruby
+require "timeout"
+
+answer = parent.approve_hosted_child(parent_execution_id,
+  execution_id: first.execution_id, approval_request_id: first.id, approved: true)
+second = Timeout.timeout(12) { approval_events.pop }
+wait = answer.detach!(execution_id: second.execution_id, approval_request_id: second.id)
+```
+
+After release, `answer.wait_result` returns the same child `ApprovalWait`.
+B sends the existing parent and child execution IDs and the **new** approval
+request ID to C. C restores the pair as B did and answers the new request.
+The completed first Tool stays recorded in the child execution. While the hosted
+answer is pending, read the saved execution to report progress. Calling
+`parent.resume` again can advance the parent revision and invalidate the
+handoff. Resume the parent after the child finishes. A host handling
+arbitrary conversations must observe both approval events and handle completion
+(`on_complete`), since the child can finish without requesting another Tool.
+
+A later user request can also start a new hosted execution on the same parent
+Agent. Its own child wait can be detached while the earlier terminal
+execution's native slot history is still retained.
+
+A wrong approval, another reserved child, overlapping local work, or a pending
+cancellation prevents transfer. On `AgentBusyError` the host keeps ownership.
+The child remains a coordinated execution in storage, including its original
+slot and retention. Once both executions complete in B, these retentions
+continue to guard ordinary `unload!`. This handoff preserves slot history.
+An application that has finished using that history can separately call
+`stores.multi_agent.forget_subagents(agent_id:, execution_id:)` to remove
+that execution's subagent extension and release its holds.
+The host serializes workers and owns request deduplication, claims, crash
+recovery and acknowledgement.
+
+## Releasing a completed Orchestrator and child
+
+A host can release the local owners once the parent has imported its direct
+child's outcome and both executions have finished. Phronomy keeps the durable
+reservation, execution results and both Agents' transcripts. A later worker
+can load the parent by its Agent ID and use that conversation for another turn.
+
+For example, after answering the last approval, the worker first lets the
+parent import the child's result. It then passes both execution IDs to the
+Orchestrator, on a host thread holding exclusive delivery for the pair. Call
+this outside an application persistence transaction so the ownership decision
+uses committed records.
+
+```ruby
+result = parent.resume(parent_execution_id)
+parent.unload_with_completed_child!(parent_execution_id,
+  execution_id: child_execution_id)
+```
+
+The method returns true on release. The parent and any matching resident child
+leave the local runtime registry together. Retrying on the released parent
+object returns false. A parent reloaded on its own can use the saved pair's IDs
+to unload without materializing the child. To display saved results without
+loading either Agent, use the Agent Store.
+
+A child may be complete while the parent is still waiting to import its result.
+In that case release is premature. Keep the host claim, finish the parent and
+then release. Active operations, a scoped owner or a conflicting retention can
+also prevent release. The method covers one imported, directly registered child
+of the specified execution. It does not sweep other child instances that the
+application previously left resident.
+
+Generic `unload!` and durable deletion continue to honor retention. Use
+`forget_subagents` only when the application intends to remove the stored
+coordination history. Once a host no longer needs an unloaded Agent, it can
+drop its own references to that instance and its operation handles.
+
+## Delivering an event to a saved Workflow wait
+
+A worker can restore a particular visit to a declared Workflow wait. The host holds
+one claim for the Workflow instance, selects the matching Workflow definition,
+and identifies the saved revision that should receive the event.
+
+For example, a parent waiting for a review stores the child's Agent and execution
+IDs in its context. A worker verifies the completed child result against those IDs.
+While it owns the parent claim, it calls the following method with the revision
+recorded for that wait:
+
+```ruby
+workflow.send_saved_event(workflow_instance_id: parent_id,
+  expected_revision: wait_revision, event: :review_ready, input: {answer: answer})
+```
+
+A later visit can have the same phase and fields but a different revision. The
+earlier delivery raises `Persistence::StateConflictError` before its transition
+executes. A transition whose guard rejects the input raises `ArgumentError` and
+leaves the checkpoint available for a corrected event. After an
+acknowledgement is lost, the host checks the durable parent state for evidence
+of this child's result before acknowledging or retrying the message. It must
+retain the original wait revision throughout retries.
+
+The host keeps its claim from reading the parent through committing the transition.
+Two workers could otherwise both run application actions before storage detects a
+conflict. The application must also restore the same Workflow definition and
+configuration. A revision identifies a stored state for one durable instance;
+do not delete and reuse its ID while old deliveries might still arrive. The
+revision does not identify deployed code or make an external Tool effect repeatable.
+A pending in-process `task_state` cannot be restored with this operation.
+
 ## Further design records
 
 The `docs/decisions/` directory contains the historical and current Architecture

data/lib/phronomy/agent/approval_wait.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Immutable reference to one committed standalone approval boundary.
+    ApprovalWait = Data.define(:execution_id, :approval_request_id, :execution_revision)
+  end
+end

data/lib/phronomy/agent/async_event_api.rb

@@ -12,12 +12,33 @@ module Phronomy
     # - approval notifications share the Agent listener as :approval_required;
     # - Recovery resolution uses resolve/resolve_async.
     module AsyncEventApi
-      def start_reserved_async(reservation:, input:, config: {}, output_schema: nil)
+      # Starts a fresh, standalone execution. Only this handle can detach its wait.
+      # The caller holds the external exclusive claim for this Agent.
+      def start_hosted(reservation:, input:, config: {}, output_schema: nil, schema_delivery: nil)
+        __with_operation do
+          if Phronomy::WaitPolicy.blocking_forbidden?
+            raise Phronomy::EventLoopReentrancyError, "start_hosted requires a host thread"
+          end
+          unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id && reservation.correlation.nil?
+            raise ArgumentError, "expected a standalone reservation for this Agent"
+          end
+          id = reservation.execution_id
+          unless persistence.observe_execution(agent_id: agent_id, execution_id: id).absent?
+            raise Phronomy::Persistence::StateConflictError, "Hosted execution #{id} already exists"
+          end
+          config = _prepare_output_config(config, nil, output_schema, schema_delivery)
+          task = _start_agent_operation(input, config: config.merge(phronomy_reserved_execution_id: id),
+            mode: :invoke, listener: _phronomy_event_listener)
+          build_hosted_invocation(id, task)
+        end
+      end
+
+      def start_reserved_async(reservation:, input:, config: {}, output_schema: nil, schema_delivery: nil)
         __with_operation(async: true) do
           unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
             raise ArgumentError, "reservation must belong to this Agent"
           end
-          config = __invocation_config(_prepare_output_config(config, nil, output_schema))
+          config = __invocation_config(_prepare_output_config(config, nil, output_schema, schema_delivery))
           ExactExecution.start(agent: self, execution_id: reservation.execution_id, input: input,
             config: config.merge(phronomy_reservation: reservation.correlation))
         end
@@ -54,12 +75,13 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _check_event_loop_reentrancy(:invoke, :invoke_async)
           _start_agent_operation(
             input,
@@ -75,12 +97,13 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation(async: true) do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _start_agent_operation(
             input,
             config: config,
@@ -95,13 +118,14 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
           listener = _required_stream_listener!(:stream)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _check_event_loop_reentrancy(:stream, :stream_async)
           _start_agent_operation(
             input,
@@ -117,13 +141,14 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation(async: true) do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
           listener = _required_stream_listener!(:stream_async)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _start_agent_operation(
             input,
             config: config,
@@ -206,9 +231,53 @@ module Phronomy
 
       private
 
-      def _prepare_output_config(config, invocation_context, schema)
+      # An optional composition hook validates the durable parent/child relation.
+      def hosted_child_approval_reader = nil
+
+      def build_hosted_invocation(id, task)
+        reader = hosted_child_approval_reader
+        return HostedInvocation.new(self, id, task) unless reader
+
+        HostedInvocation.new(self, id, task) do |execution_id, approval_id|
+          owner = __execution_environment.registry.agent_execution_owner(execution_id)
+          reader.call(agent_id, id, execution_id, approval_id, live_child: owner.agent) if owner
+        end
+      end
+
+      def resume_hosted_child_approval(parent_execution_id, execution_id:, approval_request_id:, approved:, config:)
+        __with_operation do
+          if Phronomy::WaitPolicy.blocking_forbidden?
+            raise Phronomy::EventLoopReentrancyError, "approve_hosted_child requires a host thread"
+          end
+          reader = hosted_child_approval_reader
+          parent_wait = execution_coordinator.recovered_coordination_wait
+          unless reader && parent_wait && parent_wait.execution_id == parent_execution_id && parent_wait.current?
+            raise Phronomy::AgentBusyError, "Parent has no matching recovered coordination wait"
+          end
+          owner = __execution_environment.registry.agent_execution_owner(execution_id)
+          unless owner&.status == :suspended
+            raise Phronomy::AgentBusyError, "No matching local child approval wait"
+          end
+          lookup = lambda do |child_execution_id, approval_id|
+            reader.call(agent_id, parent_execution_id, child_execution_id, approval_id,
+              parent_revision: parent_wait.revision, live_child: owner.agent)
+          end
+          wait = lookup.call(execution_id, approval_request_id)
+          raise Phronomy::AgentBusyError, "No matching hosted child approval wait" unless wait
+          task = owner.coordinator.resume(wait.execution_id, approval_request_id: wait.approval_request_id, approved: approved,
+            config: owner.agent._prepare_invocation_config(config, nil), parent_wait: parent_wait)
+          HostedInvocation.new(self, parent_execution_id, task, resumed_from: wait, &lookup)
+        end
+      end
+
+      def _prepare_output_config(config, invocation_context, schema, schema_delivery)
         config = _prepare_invocation_config(config, invocation_context)
-        schema.nil? ? config : config.merge(phronomy_output_contract: OutputContract.new(schema))
+        if schema.nil?
+          raise ArgumentError, "schema_delivery requires output_schema" unless schema_delivery.nil?
+          return config
+        end
+        contract = OutputContract.new(schema, schema_delivery: schema_delivery.nil? ? :native : schema_delivery)
+        config.merge(phronomy_output_contract: contract)
       end
 
       def _start_agent_operation(input, config:, mode:, listener:)

data/lib/phronomy/agent/base.rb

@@ -400,6 +400,31 @@ module Phronomy
         end
       end
 
+      # Materializes the current durable transcript as immutable Message values.
+      # Application authorization and presentation filtering remain caller-owned.
+      # @return [Array<LLMAdapter::Message>]
+      # @api public
+      def transcript_messages
+        _check_event_loop_reentrancy(:transcript_messages, :transcript_messages_async)
+        transcript_messages_async.wait_result
+      end
+
+      # Holds Agent ownership until the submitted read physically completes.
+      # @return [TaskResult<Array<LLMAdapter::Message>>]
+      # @api public
+      def transcript_messages_async
+        __with_operation(async: true, read_only: true) do
+          __execution_environment.submit(on_full: :raise) do
+            root, records = persistence.transaction do |tx|
+              current = tx.agents.load(agent_id)
+              [current, tx.journals.read(agent_id, limit: current.journal_position)]
+            end
+            RuntimeInput.new(agent: self, persistence: persistence)
+              .materialize_transcript(root: root, records: records)
+          end
+        end
+      end
+
       def clear_transcript!
         __with_operation do
           mutate_context!(:transcript_cleared) do |root|
@@ -727,11 +752,11 @@ module Phronomy
         true
       end
 
-      def _prepare_invocation_config(config, invocation_context)
+      protected def _prepare_invocation_config(config, invocation_context)
         __assert_live_agent!
         _reject_removed_generic_identity_keys!(config)
-        if config.keys.any? { |key| %w[output_schema response_schema phronomy_output_contract].include?(key.to_s) }
-          raise ArgumentError, "Use the output_schema keyword on a new Agent execution"
+        if config.keys.any? { |key| %w[output_schema schema_delivery response_schema phronomy_output_contract].include?(key.to_s) }
+          raise ArgumentError, "Use the output_schema and schema_delivery keywords on a new Agent execution"
         end
         invocation_context ?
           config.merge(invocation_context: invocation_context) : config

data/lib/phronomy/agent/composition/run_once.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# This convenience API composes a fresh ephemeral Persistence with an Agent.
+# This convenience API owns a fresh ephemeral Persistence and a scoped Agent.
 # The application entry loads the method definition; Agent execution does not
 # delegate to or require this higher-level composition implementation.
 module Phronomy
@@ -18,15 +18,16 @@ module Phronomy
         raise ArgumentError, "Provide either on_event: or a block, not both"
       end
 
-      persistence = Phronomy::PersistenceComposition.agent
-      agent = definition.create(
-        context: context,
-        knowledge: knowledge,
-        persistence: persistence,
-        on_event: on_event,
-        &event_block
-      )
-      agent.invoke(input, **invoke_options)
+      open_scope do |scope|
+        persistence = Phronomy::PersistenceComposition.agent
+        agent = scope.create(definition,
+          context: context,
+          knowledge: knowledge,
+          persistence: persistence,
+          on_event: on_event,
+          &event_block)
+        agent.invoke(input, **invoke_options)
+      end
     end
   end
 end

data/lib/phronomy/agent/context_preparation.rb

@@ -251,6 +251,7 @@ module Phronomy
         tools:,
         current_input:
       )
+        OutputContract.validate_model_config!(model_config) if execution.metadata.key?("output_contract")
         token_budget = Phronomy::Agent::Settings.current.llm_adapter.input_budget(model_config)
         policy_input = @input_builder.build(
           agent_id: agent_root.agent_id,

data/lib/phronomy/agent/execution/dispatch_preparation.rb

@@ -123,7 +123,7 @@ module Phronomy
         manifest, manifest_ref = @persistence.transaction do |tx|
           assert_local_durable_base!(tx, operation.root)
           Phronomy::Context::Assembly.new.store(prepared, contents: tx.contents,
-            response_schema_ref: recorded.metadata.dig("output_contract", "schema_ref"))
+            response_schema_ref: OutputContract.response_schema_ref(recorded.metadata))
         end
         updated = execution_with_provider_manifest(recorded, manifest_ref)
         change = ExecutionChange.new(agent: @agent, current: operation.execution,

data/lib/phronomy/agent/execution/exact_execution.rb

@@ -122,9 +122,11 @@ module Phronomy
           raise Phronomy::Persistence::StateConflictError, "Reserved execution #{@id} correlation mismatch"
         end
         unless @resume_only
-          expected_digest = @config[:phronomy_output_contract]&.digest
-          if expected_digest != execution.metadata.dig("output_contract", "schema_digest")
-            raise Phronomy::Persistence::StateConflictError, "Reserved execution output schema mismatch"
+          expected_contract = @config[:phronomy_output_contract]
+          saved_contract = OutputContract.restore(execution, @agent.persistence.contents)
+          if expected_contract&.digest != saved_contract&.digest ||
+              expected_contract&.schema_delivery != saved_contract&.schema_delivery
+            raise Phronomy::Persistence::StateConflictError, "Reserved execution output contract mismatch"
           end
         end
         ref = execution.metadata["current_input_ref"]
@@ -154,6 +156,10 @@ module Phronomy
       end
 
       def reconcile(failure)
+        # A suspended exact observer may already have released its operation.
+        # A logically cancelled observer still needs physical acknowledgement.
+        return if @completion.physical_complete?
+
         task = @environment.submit(on_full: :raise) do
           execution = read_execution
           if execution&.terminal?

data/lib/phronomy/agent/execution/execution_coordinator.rb

@@ -21,6 +21,36 @@ module Phronomy
         :approved, :config, :result_task
       )
 
+      # A resumed approval must never be adopted by the original start handle.
+      # Only a hosted decision owns the right to detach its next suspension.
+      class ApprovalOperation < OperationResult
+        attr_reader :parent_wait
+
+        def initialize(agent:, name:, parent_wait:)
+          super(agent: agent, name: name)
+          @parent_wait = parent_wait
+        end
+      end
+
+      # The recovery runner uses this task for replay of a framework Tool batch.
+      # @api private
+      class FrameworkRecoveryTask < Phronomy::TaskResult
+      end
+
+      # Recovery publishes a receipt only after its own coordination commit.
+      # The receipt belongs to this incarnation; a new local attempt invalidates it.
+      RecoveredCoordinationWait = Data.define(:coordinator, :execution_id, :revision) do
+        def current? = coordinator.current_coordination_wait?(self)
+      end
+      private_constant :ApprovalOperation, :RecoveredCoordinationWait
+      attr_reader :recovered_coordination_wait
+
+      def current_coordination_wait?(wait)
+        environment = @agent.__execution_environment
+        @recovered_coordination_wait.equal?(wait) && environment.ownership.owned?(@agent) &&
+          !environment.registry.agent_execution_admitted?(@agent.agent_id)
+      end
+
       # Recovery -> execution-owner commands. These stay on EventLoop and do
       # not carry persistence readers or arbitrary private method names.
       RecoverPreparationCommand = Data.define(
@@ -74,6 +104,7 @@ module Phronomy
       TerminalCommitReady = Data.define(
         :coordinator, :operation, :delivery, :outcome, :error
       )
+      DetachHostedWait = Data.define(:coordinator, :wait, :task, :parent, :completion)
       SuspensionCancelledCommand = Data.define(:coordinator, :execution_id)
 
       DeferredTerminalCommand = Data.define(
@@ -125,11 +156,11 @@ module Phronomy
         execution_id,
         approval_request_id:,
         approved:,
-        config: {}
+        config: {}, parent_wait: nil
       )
         @agent.send(:__assert_live_agent!)
         @agent.send(:_reject_removed_generic_identity_keys!, config)
-        result_task = OperationResult.new(agent: @agent,
+        result_task = ApprovalOperation.new(agent: @agent, parent_wait: parent_wait,
           name: "agent-approval-resume:#{execution_id}")
         command = ResumeCommand.new(
           coordinator: self,
@@ -248,6 +279,8 @@ module Phronomy
           apply_provider_dispatch_preparation_on_event_loop(command)
         when ToolDispatchPreparationReady
           apply_tool_dispatch_preparation_on_event_loop(command)
+        when DetachHostedWait
+          detach_hosted_wait(command, environment)
         when ResumeCommand
           begin_resume_on_event_loop(command)
         when ResumeCommitReady
@@ -265,6 +298,47 @@ module Phronomy
 
       private
 
+      # Called on EventLoop after the host has read the committed wait outside it.
+      def detach_hosted_wait(command, environment)
+        wait = command.wait
+        registry = environment.registry
+        state = registry.agent_execution_state(wait.execution_id)
+        binding = @suspended_cancellation
+        task = command.task || binding&.fetch(2)
+        parent = command.parent
+        if task.is_a?(ApprovalOperation) && (!command.task.equal?(task) || !task.parent_wait&.current?)
+          raise Phronomy::AgentBusyError, "This handle does not own the resumed child wait"
+        end
+        if parent && registry.agent_execution_admitted?(parent.agent_id)
+          raise Phronomy::AgentBusyError, "Hosted parent has another local execution"
+        end
+        unless state && state.agent.equal?(@agent) && state.execution.status == :suspended &&
+            state.execution.execution_revision == wait.execution_revision && state.fsm_session_id.nil? &&
+            state.execution.approval_request&.fetch("id", nil) == wait.approval_request_id &&
+            binding && task.is_a?(OperationResult) && binding[1].equal?(state.invocation) && binding[2].equal?(task) &&
+            !state.invocation.config[:cancellation_token]&.cancelled? && registry.agent_execution_quiescent?(wait.execution_id)
+          raise Phronomy::AgentBusyError, "Hosted operation no longer owns this approval wait"
+        end
+        registry.mark_agent_execution_admission(@agent.agent_id, execution_id: wait.execution_id,
+          state: :suspended, expected_state: :suspended)
+        task.reserve_approval_detach!(command, parent: parent)
+        begin
+          # release_agent_execution validates all remaining physical work before mutation.
+          registry.release_agent_execution(wait.execution_id)
+        rescue
+          environment.ownership.finish_unload(@agent, command, success: false, parent: parent)
+          raise
+        end
+        clear_suspended_cancellation
+        registry.release_agent_execution_admission(@agent.agent_id, execution_id: wait.execution_id)
+        waiters = registry.take_agent_completion_waiters(wait.execution_id, fallback: task)
+        environment.ownership.finish_unload(@agent, command, success: true, parent: parent)
+        waiters.each { |waiter| @agent.send(:_complete_result_task, waiter, wait) }
+        command.completion.complete(wait)
+      rescue => error
+        command.completion.fail(error)
+      end
+
       # ----------------------------------------------------------------------
       # Initial preparation
       # ----------------------------------------------------------------------
@@ -296,6 +370,7 @@ module Phronomy
         # must abort instead of deleting the Agent underneath this start.
         @agent.send(:__assert_live_agent!)
 
+        @recovered_coordination_wait = nil
         operation = capture_initial_preparation(request, root)
         task = environment.submit(on_full: :raise) do
           @initial_preparation.prepare(operation)
@@ -901,6 +976,12 @@ module Phronomy
           return
         end
 
+        if request.result_task.is_a?(ApprovalOperation) && (parent_wait = request.result_task.parent_wait)
+          unless parent_wait.current? && !@suspended_cancellation
+            return fail_task(request.result_task, Phronomy::AgentBusyError.new("Hosted decision requires a restored child wait"))
+          end
+        end
+
         approval = state.execution.approval_request || {}
         current_request_id = approval["id"] || approval[:id]
         unless current_request_id.to_s == request.approval_request_id
@@ -1088,6 +1169,7 @@ module Phronomy
         environment = @agent.__execution_environment
         registry = environment.registry
         state = recovered_execution_state!(command)
+        @recovered_coordination_wait = nil
         validate_recovered_continuation!(state.execution, command.continuation)
         invocation = command.invocation
         unless invocation && invocation.agent.equal?(@agent) &&
@@ -1495,6 +1577,11 @@ module Phronomy
         delivery = ready.delivery
         outcome = ready.outcome
         release_terminal_ownership(environment, operation.execution_id, state)
+        if delivery.result_task.is_a?(OperationResult)
+          delivery.result_task.coordination_wait_execution_id = operation.execution_id
+        elsif delivery.result_task.is_a?(FrameworkRecoveryTask)
+          @recovered_coordination_wait = RecoveredCoordinationWait.new(self, operation.execution_id, outcome.execution.execution_revision)
+        end
         environment.registry.take_agent_completion_waiters(operation.execution_id, fallback: delivery.result_task).each { |task| fail_task(task, outcome.error) }
       end
 
@@ -1703,6 +1790,12 @@ module Phronomy
           execution_id,
           fallback: fallback_task
         )
+        # All these waiters observe the same terminal execution. A synchronous
+        # completion callback may request unload immediately, so acknowledge
+        # every finished operation before publishing any logical result. Each
+        # OperationResult still retains its lease until tracked physical work
+        # ends; unrelated operations remain protected by their own leases.
+        waiters.each { |task| task.finish_operation! if task.respond_to?(:finish_operation!) }
         waiters.each do |task|
           settle_after_terminal(
             task, callback_error, event_type, result, execution_error

data/lib/phronomy/agent/execution/execution_outcome_committer.rb

@@ -286,12 +286,7 @@ module Phronomy
           agent: @agent,
           persistence: persistence
         )
-        materializer.materialize_journal_records(
-          JournalProjection.new(
-            agent_root: root,
-            records: journal_records
-          ).transcript_records
-        )
+        materializer.materialize_transcript(root: root, records: journal_records)
       end
 
       def result_base(execution, root)

data/lib/phronomy/agent/execution/initial_preparation.rb

@@ -192,7 +192,7 @@ module Phronomy
         @persistence.transaction do |tx|
           assert_local_durable_base!(tx, root)
           manifest, manifest_ref = Phronomy::Context::Assembly.new.store(prepared, contents: tx.contents,
-            response_schema_ref: staged.metadata.dig("output_contract", "schema_ref"))
+            response_schema_ref: OutputContract.response_schema_ref(staged.metadata))
           active = execution_with_initial_manifest(staged, manifest_ref)
           tx.executions.save(
             staged.execution_id,