smith-agents 0.7.0 → 0.10.0

data/lib/smith/workflow/failure_record_text.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../diagnostic_text"
+require_relative "../errors"
+
+module Smith
+  class Workflow
+    class FailureRecordText
+      # Deterministic stand-in shared by capture and restore for failure
+      # messages that would otherwise be blank.
+      MISSING_TEXT = "failure message unavailable"
+
+      MODULE_MATCH = Module.instance_method(:===)
+      STRING_BYTESIZE = String.instance_method(:bytesize)
+      STRING_ENCODING = String.instance_method(:encoding)
+      STRING_INITIALIZE_COPY = String.instance_method(:initialize_copy)
+      STRING_VALID_ENCODING = String.instance_method(:valid_encoding?)
+      SYMBOL_TO_S = Symbol.instance_method(:to_s)
+      private_constant :MODULE_MATCH, :STRING_BYTESIZE, :STRING_ENCODING, :STRING_INITIALIZE_COPY,
+                       :STRING_VALID_ENCODING, :SYMBOL_TO_S
+
+      extend Dry::Initializer
+
+      param :value
+      option :limit
+      option :label
+      option :normalize_length, default: proc { false }
+
+      def self.capture(value, limit:, label:, normalize_length: false)
+        new(value, limit:, label:, normalize_length:).call
+      end
+
+      def call
+        text = owned_text
+        validate_encoding!(text)
+        size = STRING_BYTESIZE.bind_call(text)
+        return normalized(text, size) if normalize_length
+        raise PersistedFailureInvalid, "persisted workflow failure #{label} is invalid" unless size.between?(1, limit)
+
+        text.freeze
+      end
+
+      private
+
+      def validate_encoding!(text)
+        valid = STRING_VALID_ENCODING.bind_call(text) && STRING_ENCODING.bind_call(text) == Encoding::UTF_8
+        return if valid
+
+        raise PersistedFailureInvalid, "persisted workflow failure #{label} is invalid"
+      end
+
+      # Message fields mirror capture normalization instead of rejecting on
+      # length: legacy states persisted messages unbounded (and possibly
+      # blank), and failing the whole workflow restore for message length
+      # alone would poison otherwise valid durable state. Blank text takes
+      # the capture placeholder; overlong text truncates exactly like
+      # capture does.
+      def normalized(text, size)
+        return MISSING_TEXT if size.zero?
+        return text.freeze if size <= limit
+
+        DiagnosticText.capture(text, max_bytes: limit)
+      end
+
+      def owned_text
+        return owned_string if string?
+        return SYMBOL_TO_S.bind_call(value) if symbol?
+
+        raise PersistedFailureInvalid, "persisted workflow failure #{label} must be text"
+      end
+
+      def owned_string
+        String.allocate.tap { STRING_INITIALIZE_COPY.bind_call(_1, value) }
+      end
+
+      def string? = MODULE_MATCH.bind_call(String, value)
+
+      def symbol? = MODULE_MATCH.bind_call(Symbol, value)
+    end
+  end
+end

data/lib/smith/workflow/failure_record_validator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+require_relative "../errors"
+require_relative "composite/branch_failure"
+
+module Smith
+  class Workflow
+    class FailureRecordValidator
+      KNOWN_ERROR_FAMILIES = {
+        "Smith::DeterministicStepFailure" => "deterministic_step_failure",
+        "Smith::ToolGuardrailFailed" => "tool_guardrail_failed",
+        "Smith::ToolCaptureFailed" => "tool_capture_failed",
+        "Smith::ToolFailureNotificationFailed" => "tool_failure_notification_failed",
+        "Smith::ToolOutcomeUncertain" => "tool_outcome_uncertain",
+        "Smith::ToolExecutionNotAdmitted" => "tool_execution_not_admitted",
+        "Smith::BoundedCompletionError" => "bounded_completion_error",
+        "Smith::PersistedFailureInvalid" => "persisted_failure_invalid",
+        "Smith::AgentError" => "agent_error",
+        "Smith::BlankAgentOutputError" => "agent_error",
+        "Smith::DeadlineExceeded" => "deadline_exceeded",
+        "Smith::WorkflowError" => "workflow_error",
+        "Smith::UnresolvedTransitionError" => "workflow_error",
+        "Smith::Workflow::Composite::BranchFailure" => "workflow_error"
+      }.freeze
+      KNOWN_FAMILIES = %w[
+        deterministic_step_failure tool_guardrail_failed tool_failure_notification_failed tool_capture_failed
+        tool_outcome_uncertain tool_execution_not_admitted bounded_completion_error persisted_failure_invalid
+        deadline_exceeded agent_error workflow_error other
+      ].freeze
+      RETRY_FORBIDDEN_FAMILIES = %w[
+        tool_capture_failed tool_failure_notification_failed tool_outcome_uncertain tool_execution_not_admitted
+        bounded_completion_error persisted_failure_invalid
+      ].freeze
+      DETAIL_VALIDATORS = {
+        "Smith::ToolCaptureFailed" => ->(details) { Smith::ToolCaptureFailed.from_details(details) },
+        "Smith::ToolFailureNotificationFailed" => lambda { |details|
+          Smith::ToolFailureNotificationFailed.from_details(details)
+        },
+        "Smith::Workflow::Composite::BranchFailure" => lambda { |details|
+          Smith::Workflow::Composite::BranchFailure.from_details(details)
+        }
+      }.freeze
+      BOOLEAN_VALUES = [true, false].freeze
+      private_constant :KNOWN_ERROR_FAMILIES, :KNOWN_FAMILIES, :RETRY_FORBIDDEN_FAMILIES, :DETAIL_VALIDATORS,
+                       :BOOLEAN_VALUES
+
+      extend Dry::Initializer
+
+      param :snapshot
+
+      def call
+        validate_family!
+        validate_class_family!
+        validate_retry_policy!
+        validate_cause!
+        validate_details!
+        snapshot
+      rescue ArgumentError, KeyError, TypeError
+        reject!("persisted workflow failure details are invalid")
+      end
+
+      private
+
+      def family = snapshot[:error_family]
+
+      def validate_family!
+        return if KNOWN_FAMILIES.include?(family)
+
+        reject!("persisted workflow failure family is invalid")
+      end
+
+      def validate_class_family!
+        expected = KNOWN_ERROR_FAMILIES[snapshot[:error_class]]
+        return unless expected && family != expected
+
+        reject!("persisted workflow failure class and family disagree")
+      end
+
+      def validate_retry_policy!
+        forbidden = snapshot[:error_retry_forbidden]
+        return if forbidden.nil?
+
+        reject!("persisted workflow failure retry policy is invalid") unless BOOLEAN_VALUES.include?(forbidden)
+        return if forbidden == RETRY_FORBIDDEN_FAMILIES.include?(family)
+
+        reject!("persisted workflow failure retry policy disagrees with its family")
+      end
+
+      # Cause classification travels as one unit: capture writes all three
+      # attributes together for uncertainty wrappers, so a partial set is
+      # corrupt data rather than a legacy shape (legacy records omit all
+      # three).
+      def validate_cause!
+        cause_values = snapshot.values_at(:error_cause_class, :error_cause_family, :error_cause_message)
+        return if cause_values.all?(&:nil?)
+
+        reject!("persisted workflow failure cause is incomplete") if cause_values.any?(&:nil?)
+        return if KNOWN_FAMILIES.include?(snapshot[:error_cause_family])
+
+        reject!("persisted workflow failure cause family is invalid")
+      end
+
+      def validate_details!
+        validator = DETAIL_VALIDATORS[snapshot[:error_class]]
+        validator&.call(snapshot[:error_details])
+      end
+
+      def reject!(message) = raise(Smith::PersistedFailureInvalid, message)
+    end
+  end
+end

data/lib/smith/workflow/fanout_execution.rb

@@ -51,7 +51,7 @@ module Smith
       end
 
       def run_fanout_branch(branch_key, agent_name, agent_class, env, signal)
-        with_branch_context(env, @ledger, agent_class:) do
+        with_branch_context(env, @ledger, agent_class:, attribution_overlay: { branch_key: }) do
           with_agent_context(agent_class) do
             branch_ledger = effective_call_ledger
             reserved = reserve_fanout_branch_call(branch_ledger, env.branch_estimates[branch_key], agent_class)

data/lib/smith/workflow/guarded_step_execution.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    module GuardedStepExecution
+      private
+
+      def run_guarded_step(transition)
+        tracker = Tool::ExecutionTracker.new
+        previous_tracker = Tool.current_tool_execution_tracker
+
+        Thread.handle_interrupt(Object => :never) do
+          Tool.current_tool_execution_tracker = tracker
+          begin
+            Thread.handle_interrupt(Object => :immediate) { run_tracked_guarded_step(transition) }
+          rescue StandardError => e
+            raise unless tracker.started?
+            raise if terminal_retry_error?(e)
+
+            raise ToolOutcomeUncertain.new(
+              "transition failed after tool execution began; retry could replay an uncertain outcome"
+            ), cause: e
+          ensure
+            Tool.current_tool_execution_tracker = previous_tracker
+          end
+        end
+      end
+
+      def run_tracked_guarded_step(transition)
+        return apply_composite_reduction!(transition) if @composite_reduction
+
+        @resolved_parallel_branch_count = preflight_branch_count(transition)
+        run_standard_guarded_step(transition)
+      ensure
+        @resolved_parallel_branch_count = nil
+      end
+    end
+  end
+end

data/lib/smith/workflow/guardrail_integration.rb

@@ -24,6 +24,12 @@ module Smith
 
       def handle_step_failure(transition, error)
         step = { transition: transition.name, from: transition.from, to: transition.to, error: error }
+        # Staged, not emitted: this rescue runs under the step snapshot's
+        # interrupt mask, and host StepFailed handlers must not execute
+        # unkillable. with_step_context flushes after the mask closes.
+        # Staged before the split-step capture so a capture invariant
+        # failure still flushes an emission for the original error.
+        @pending_step_failure = step
         SplitStepPersistence
           .instance_method(:capture_split_step_execution_result!)
           .bind_call(self, step)
@@ -50,9 +56,28 @@ module Smith
 
         @outcome = nil
         step = { transition: error.requested_name, from: @state, to: fail_transition.to, error: error }
+
+        # A step body that raised UnresolvedTransitionError was already
+        # captured, staged, and emitted under its real transition identity
+        # by the step-failure path before advance!'s rescue reached here.
+        # Capturing or emitting again would record the same failure twice,
+        # the second time under the requested name, a transition that never
+        # executed. Routing to :fail still happens either way.
+        if error.equal?(@emitted_step_failure_error)
+          @state = fail_transition.to
+          return step
+        end
+
         SplitStepPersistence
           .instance_method(:capture_split_step_execution_result!)
           .bind_call(self, step)
+        # Unlike the step-body path, this handler runs outside any step
+        # context (advance! rescues UnresolvedTransitionError after the step
+        # unwound), so the run identity must be seeded here or the emitted
+        # facts get fallback random ids.
+        Attribution.with(execution_key: @persistence_key, workflow: self.class.name || "anonymous") do
+          emit_step_failed(step)
+        end
         @state = fail_transition.to
         step
       end

data/lib/smith/workflow/parallel.rb

@@ -38,11 +38,22 @@ module Smith
 
       def self.preferred_error(reasons)
         errors = Array(reasons).compact
-        errors.find { |error| !error.is_a?(StandardError) } ||
-          errors.find { |error| error.is_a?(ToolCaptureFailed) } ||
-          errors.find { |error| !error.is_a?(Cancellation) } ||
+        process_fatal_error(errors) ||
+          notification_failure(errors) ||
+          terminal_execution_error(errors) ||
+          ordinary_error(errors) ||
           errors.first
       end
+
+      def self.process_fatal_error(errors) = errors.find { !_1.is_a?(StandardError) }
+
+      def self.notification_failure(errors) = errors.find { _1.is_a?(ToolFailureNotificationFailed) }
+
+      def self.terminal_execution_error(errors) = errors.find { Smith::Errors.retry_forbidden?(_1) }
+
+      def self.ordinary_error(errors) = errors.find { !_1.is_a?(Cancellation) }
+
+      private_class_method :process_fatal_error, :notification_failure, :terminal_execution_error, :ordinary_error
     end
   end
 end

data/lib/smith/workflow/parallel_execution.rb

@@ -60,6 +60,7 @@ module Smith
         ledger,
         parallel_agent_binding: NO_PARALLEL_BINDING,
         agent_class: nil,
+        attribution_overlay: nil,
         &block
       )
         snapshot = ThreadContextSnapshot.new
@@ -69,6 +70,11 @@ module Smith
           else
             setup_branch_context(env, ledger)
           end
+
+          # Restoration is owned by the snapshot above, which tracks the
+          # attribution thread key.
+          Attribution.install(Attribution.ambient.merge(**attribution_overlay)) if attribution_overlay
+
           unless parallel_agent_binding.equal?(NO_PARALLEL_BINDING)
             Thread.current[:smith_parallel_agent_binding] = parallel_agent_binding
           end

data/lib/smith/workflow/persistence.rb

@@ -26,8 +26,12 @@ module Smith
           # snapshot_value so non-JSON-safe runtime values (e.g.
           # custom Hash details on DeterministicStepFailure) get the
           # same deep-copy treatment as context/session_messages/etc.
-          usage_entries: snapshot_value((@usage_entries || []).map(&:to_h)),
+          usage_entries: snapshot_value(usage_entries_for_state.map(&:to_h)),
           last_output: snapshot_value(@last_output),
+          # Durable { model:, provider: } of the most recent serial agent step,
+          # so a deterministic step that resumes after the agent step (across a
+          # crash) still reads its `last_agent_model` / `last_agent_provider`.
+          last_agent_execution: snapshot_value(@last_agent_execution),
           last_failed_step: snapshot_value(@last_failed_step),
           # Optimistic-locking version. Adapters that support
           # store_versioned use this to detect concurrent writes; adapters
@@ -48,6 +52,10 @@ module Smith
           # cycles so seed_validation can detect when the seed builder
           # has changed in code since this workflow was persisted.
           seed_digest: @seed_digest,
+          # Number of immutable seed messages at the beginning of session
+          # history. Context strategies may preserve this exact prefix while
+          # masking later workflow observations.
+          seed_message_count: @seed_message_count || 0,
           # Step-in-progress idempotency marker. Set true between
           # persist-before-advance and persist-after-advance when the
           # workflow class opts into idempotency_mode :strict. Restore
@@ -76,6 +84,7 @@ module Smith
         @ledger = rebuild_ledger(normalized[:budget_consumed] || {})
         @next_transition_name = normalized[:next_transition_name]
         @session_messages = normalized[:session_messages] || []
+        @seed_message_count = validated_seed_message_count(normalized)
         @total_cost = normalized[:total_cost] || 0.0
         @total_tokens = normalized[:total_tokens] || 0
         @outcome = normalized[:outcome]
@@ -90,6 +99,12 @@ module Smith
         @usage_mutex = Mutex.new
         @usage_entries = restore_usage_entries(normalized)
         @last_output = restore_last_output(normalized)
+        # Backward-compat: pre-patch states have no last_agent_execution key and
+        # restore to nil. @pending_agent_execution is transient (nil between
+        # steps), never persisted, but must be initialized because from_state
+        # allocates and bypasses #initialize.
+        @last_agent_execution = restore_last_agent_execution(normalized)
+        @pending_agent_execution = nil
         @last_failed_step = restore_last_failed_step(normalized)
         # Restore the optimistic-locking version from the persisted payload.
         # Backward-compat: pre-versioning payloads have no key, restore to 0
@@ -120,6 +135,14 @@ module Smith
               "persisted workflow persistence_version must be a non-negative integer, got #{version.inspect}"
       end
 
+      def validated_seed_message_count(normalized)
+        count = normalized.fetch(:seed_message_count, 0)
+        return count if count.is_a?(Integer) && count >= 0 && count <= @session_messages.length
+
+        raise Smith::SerializationError,
+              "persisted workflow seed_message_count must be between 0 and session message count"
+      end
+
       def validate_definition_digest!(normalized)
         stored = normalized[:definition_digest]
         return if stored.nil?
@@ -179,6 +202,17 @@ module Smith
         raw.map { |h| Workflow::UsageEntry.from_h(h) }
       end
 
+      # Serialization reads the ledger under the recording mutex so a state
+      # written mid-fan-out never captures a torn array. The mutex can be
+      # absent on an allocated-but-unrestored instance; fall back to the
+      # bare read to_state always tolerated.
+      def usage_entries_for_state
+        mutex = @usage_mutex
+        return (@usage_entries || []).dup unless mutex
+
+        mutex.synchronize { (@usage_entries || []).dup }
+      end
+
       # Use key-presence checks (NOT `||`) so a deliberately persisted
       # `false` step output round-trips correctly. Smith's existing
       # `RunResult#output` derivation uses `compact.first`, which only
@@ -191,6 +225,17 @@ module Smith
         end
       end
 
+      def restore_last_agent_execution(normalized)
+        value = if normalized.key?(:last_agent_execution)
+          normalized[:last_agent_execution]
+        elsif normalized.key?("last_agent_execution")
+          normalized["last_agent_execution"]
+        end
+        return unless value.is_a?(Hash)
+
+        symbolize_keys(value)
+      end
+
       # Symbolize ONLY the top-level keys of last_failed_step + the
       # known value-symbols (`transition`, `from`, `to`, `error_kind`).
       # `error_family` stays a String (the family_fallback compares
@@ -200,20 +245,11 @@ module Smith
       # values become strings).
       def restore_last_failed_step(normalized)
         raw = normalized[:last_failed_step]
-        return nil unless raw.is_a?(Hash)
-
-        h = raw.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
-        {
-          transition: normalize_transition_name(h[:transition]),
-          from: normalize_state_name(h[:from]),
-          to: normalize_state_name(h[:to]),
-          error_class: h[:error_class],
-          error_family: h[:error_family],
-          error_message: h[:error_message],
-          error_retryable: h[:error_retryable],
-          error_kind: h[:error_kind]&.to_sym,
-          error_details: h[:error_details]
-        }
+        FailureRecordRestore.new(
+          raw,
+          transition_normalizer: method(:normalize_transition_name),
+          state_normalizer: method(:normalize_state_name)
+        ).call
       end
 
       def restore_core_fields(normalized)
@@ -234,9 +270,9 @@ module Smith
         end
 
         manager = self.class.context_manager
-        if manager && manager.respond_to?(:persist_mode) && manager.persist_mode == :auto
+        if manager.respond_to?(:persist_mode) && manager.persist_mode == :auto
           ctx = normalized[:context]
-          existing = ctx.is_a?(Hash) ? ctx.keys.map { |k| k.to_sym } : []
+          existing = ctx.is_a?(Hash) ? ctx.keys.map(&:to_sym) : []
           seed = manager.persist_auto_seed.map(&:to_sym)
           @persisted_keys = ::Set.new(existing + seed)
         else
@@ -309,6 +345,7 @@ module Smith
 
       def normalize_transition_name(value)
         return if value.nil?
+
         transition = self.class.find_transition(value)
         return transition.name if transition
         return value unless value.is_a?(String)
@@ -416,9 +453,7 @@ module Smith
         manager = self.class.context_manager
         return nil unless manager
 
-        if manager.respond_to?(:persist_mode) && manager.persist_mode == :auto
-          return :auto
-        end
+        return :auto if manager.respond_to?(:persist_mode) && manager.persist_mode == :auto
 
         keys = manager.persist
         keys.empty? ? nil : keys

data/lib/smith/workflow/prepared_branch_execution.rb

@@ -7,18 +7,27 @@ module Smith
 
       def prepared_branch(implementation, *arguments)
         tool_context = Tool::ScopedContext.capture
+        # Attribution is captured on the preparing thread (where the step's
+        # context is ambient) and carried into the branch thread, exactly as
+        # the tool context is; carrying nil deliberately clears stale state
+        # on a pooled thread.
+        ambient_attribution = Attribution.current
         unless @split_step_active_execution_authorization
           return proc do |signal|
-            Tool::ScopedContext.around(tool_context) do
-              __send__(implementation.name, *arguments, signal)
+            Attribution.carrying(ambient_attribution) do
+              Tool::ScopedContext.around(tool_context) do
+                __send__(implementation.name, *arguments, signal)
+              end
             end
           end
         end
 
         proc do |signal|
           run = proc { implementation.bind_call(self, *arguments, signal) }
-          Tool::ScopedContext.around(tool_context) do
-            PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+          Attribution.carrying(ambient_attribution) do
+            Tool::ScopedContext.around(tool_context) do
+              PreparedBranchExecution.instance_method(:within_prepared_branch_execution).bind_call(self, &run)
+            end
           end
         end
       end

data/lib/smith/workflow/retry_execution.rb

@@ -24,7 +24,7 @@ module Smith
 
       def retry_transition_error?(config, error, attempt)
         return false if attempt >= config.fetch(:attempts)
-        return false if error.is_a?(ToolCaptureFailed)
+        return false if terminal_retry_error?(error)
 
         classes = config.fetch(:error_classes)
         if classes.any?
@@ -34,6 +34,10 @@ module Smith
         end
       end
 
+      def terminal_retry_error?(error)
+        Smith::Errors.retry_forbidden?(error)
+      end
+
       def sleep_for_retry(schedule, failed_attempt)
         delay = retry_delay(schedule, failed_attempt)
         sleep(delay) if delay.positive?

data/lib/smith/workflow/split_step_persistence/composite_branch_execution.rb

@@ -40,7 +40,15 @@ module Smith
         end
 
         def capture_composite_branch(&block)
-          output = within_raw_step_context { with_scoped_artifacts(&block) }
+          output = within_raw_step_context do
+            # Same ambient attribution the in-process step path installs, so
+            # durably executed branches tag usage and traces identically
+            # (execution key from the restored persistence key, the split
+            # step's transition, then the branch overlay downstream).
+            # Restoration is owned by within_raw_step_context's snapshot.
+            install_step_attribution(@split_step_transition) if @split_step_transition
+            with_scoped_artifacts(&block)
+          end
           [output, nil]
         rescue StandardError => e
           [nil, e]

data/lib/smith/workflow/split_step_persistence/state_snapshot.rb

@@ -58,6 +58,7 @@ module Smith
 
         def detach_split_step_results!
           @last_output = snapshot_value(@last_output)
+          @last_agent_execution = snapshot_value(@last_agent_execution)
           @last_failed_step = snapshot_value(@last_failed_step)
           @last_prepared_input = snapshot_value(@last_prepared_input)
         end

data/lib/smith/workflow/step_completion.rb

@@ -7,6 +7,15 @@ module Smith
 
       def complete_step(transition, output)
         step = { transition: transition.name, from: transition.from, to: transition.to, output: output }
+        # Fold in the serial agent attribution captured for this step (if any),
+        # then clear the transient carrier. record_step_snapshot reads these off
+        # the returned step to update the durable @last_agent_execution.
+        if @pending_agent_execution
+          step[:model] = @pending_agent_execution[:model]
+          step[:provider] = @pending_agent_execution[:provider]
+        end
+
+        @pending_agent_execution = nil
         result = SplitStepPersistence
                  .instance_method(:prepare_split_step_execution_result)
                  .bind_call(self, step)

data/lib/smith/workflow/step_context.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../attribution"
 require_relative "thread_context_snapshot"
 
 module Smith
@@ -10,6 +11,7 @@ module Smith
       def with_step_context(transition, &block)
         ThreadContextSnapshot.new.around do
           setup_step_context
+          install_step_attribution(transition)
           Thread.handle_interrupt(Object => :immediate, &block)
         rescue StandardError => e
           @outcome = nil
@@ -17,6 +19,32 @@ module Smith
         ensure
           teardown_step_context
         end
+      ensure
+        flush_step_failure_emission
+      end
+
+      # Runs after the snapshot's interrupt mask has closed, so host
+      # StepFailed handlers execute interruptible, exactly as StepCompleted
+      # handlers do inside the step. The step context is gone by now, so the
+      # run identity and workflow label are seeded explicitly; the failed
+      # step's own transition facts travel in the staged step hash. Flushes
+      # on every exit of with_step_context, including the re-raise paths.
+      # The read-clear-mark triple is masked so an async interrupt cannot
+      # strand a staged failure between read and clear; the marker lets the
+      # unresolved-transition handler recognize an error this path already
+      # emitted. Only the emission itself stays interruptible.
+      def flush_step_failure_emission
+        step = nil
+        Thread.handle_interrupt(Object => :never) do
+          step = @pending_step_failure
+          @pending_step_failure = nil
+          @emitted_step_failure_error = step[:error] if step
+        end
+        return unless step
+
+        Attribution.with(execution_key: @persistence_key, workflow: self.class.name || "anonymous") do
+          emit_step_failed(step)
+        end
       end
 
       def within_raw_step_context(&block)
@@ -34,6 +62,24 @@ module Smith
         Tool.current_tool_result_collector = tool_result_collector
       end
 
+      # The ambient attribution for this step. Restoration is owned by the
+      # surrounding ThreadContextSnapshot (the attribution thread key is one
+      # of its THREAD_KEYS), so installation is a plain assignment. A nil
+      # persistence key preserves any host-seeded outer execution_key, and
+      # `workflow` is always a string ("anonymous" when the class has no
+      # name) so a nested child always overrides the parent's label. The
+      # per-step facts (transition, from, to) are replaced verbatim, nil
+      # included: a nested child's `from: nil` transition must not inherit
+      # the parent step's `from` through the nil-ignoring merge. branch_key
+      # and round inherit deliberately (a child genuinely runs within them).
+      def install_step_attribution(transition)
+        Attribution.install(
+          Attribution.ambient
+                     .merge(execution_key: @persistence_key, workflow: self.class.name || "anonymous")
+                     .override(transition: transition.name, from: transition.from, to: transition.to)
+        )
+      end
+
       def teardown_step_context
         Tool.current_guardrails = nil
         Tool.current_deadline = nil