smith-agents 0.8.0 → 0.11.0

data/lib/smith/workflow/evaluator_optimizer.rb

@@ -3,6 +3,7 @@
 require "json"
 
 require_relative "agent_result"
+require_relative "execution_result_snapshot"
 require_relative "optimization_state"
 
 module Smith
@@ -24,12 +25,15 @@ module Smith
           transition_name: transition.name,
           role: :evaluator
         )
+        pend_evaluations
         run_optimization_loop(state)
       end
 
       def run_optimization_loop(state)
         state.config[:max_rounds].times do |round|
-          result = run_optimization_round(state, round)
+          # The overlay scopes every trace and usage fact from this round's
+          # generator and evaluator calls to the round that produced them.
+          result = Attribution.with(round: round) { run_optimization_round(state, round) }
           return result if result
         end
 
@@ -39,10 +43,11 @@ module Smith
 
       def run_optimization_round(state, round)
         generate_candidate!(state, round)
-        invoke_before_eval(state)
-        evaluation = normalize_evaluation(evaluate_candidate(state))
+        rejection = before_eval_rejection(state)
+        evaluation = rejection || normalize_evaluation(evaluate_candidate(state))
         validate_evaluation_structure!(evaluation)
         validate_evaluation_fields!(evaluation, state.config)
+        record_evaluation(state, evaluation, round, rejection ? :before_eval : :evaluator)
 
         return state.candidate if evaluation[:accept]
 
@@ -59,6 +64,88 @@ module Smith
         nil
       end
 
+      # Each valid round's evaluation, in round order: the round, whether the
+      # evaluator or a before_eval rejection gave it, and the verdict as
+      # normalized, copied and frozen so neither the loop nor a host holding a
+      # record can change it. Recorded before any exit, so the verdict that
+      # ends the loop (accepted, converged, or under the threshold) is kept.
+      # The loop's state carries a frozen copy, so a callable reads the
+      # verdicts so far and cannot rewrite the step's.
+      def record_evaluation(state, evaluation, round, source)
+        records = @pending_evaluations.values.last
+        record = { round: round, source: source, verdict: frozen_verdict(evaluation) }.freeze
+        within_step_record_limits!(@pending_evaluations.values.flatten(1) << record)
+        records << record
+        state.evaluations = records.dup.freeze
+      end
+
+      # The verdicts ride on the step's record, which a split step snapshots
+      # under ExecutionResultSnapshot's limits. A round whose verdict would
+      # take the step's verdicts past them fails here, the same way in every
+      # run mode, and the verdicts already recorded still fit a failed step's
+      # record.
+      def within_step_record_limits!(records)
+        ExecutionResultSnapshot.new({ evaluations: records }).call
+      rescue WorkflowError => e
+        raise WorkflowError, "evaluations exceed a step record's limits: #{e.message}"
+      end
+
+      # A verdict holds JSON values only, as a provider's structured output
+      # does: anything else (an object a before_eval returned, a key that is
+      # not a String or Symbol, a non-finite Float) fails the round here, the
+      # same way in every run mode, rather than when a split step snapshots it.
+      def frozen_verdict(value)
+        case value
+        when Hash then value.to_h { |key, nested| [verdict_key(key), frozen_verdict(nested)] }.freeze
+        when Array then value.map { |nested| frozen_verdict(nested) }.freeze
+        when String then StringSnapshot.copy(value, freeze: true)
+        else verdict_scalar(value)
+        end
+      end
+
+      def verdict_scalar(value)
+        case value
+        when Float then finite_verdict_number(value)
+        when Symbol, Integer, true, false, nil then value
+        else raise WorkflowError, "evaluation must hold JSON values; got #{value.class}"
+        end
+      end
+
+      def verdict_key(key)
+        return key if key.is_a?(Symbol)
+        return StringSnapshot.copy(key, freeze: true) if key.is_a?(String)
+
+        raise WorkflowError, "evaluation keys must be Strings or Symbols; got #{key.class}"
+      end
+
+      def finite_verdict_number(value)
+        return value if value.finite?
+
+        raise WorkflowError, "evaluation must hold finite numbers; got #{value}"
+      end
+
+      # An optimize step's record carries every verdict its loops recorded
+      # under :evaluations, whether the step completed or failed, each naming
+      # the attempt that gave it (`@step_attempt`, the retry policy's): a step
+      # `retry_on` runs again starts its loop afresh, rounds counting from 0
+      # again, and an earlier attempt's verdicts were given and paid for all
+      # the same. The key is there whenever a loop ran; a step that failed
+      # before its loop (an agent not registered, a guardrail) and any other
+      # step have none. The carrier is transient: the loop's list keyed by its
+      # attempt, cleared once the step's record is committed or its failure
+      # captured, and at every step's start.
+      def pend_evaluations
+        (@pending_evaluations ||= {})[@step_attempt || 1] = []
+      end
+
+      def fold_pending_evaluations(step)
+        return unless @pending_evaluations
+
+        step[:evaluations] = @pending_evaluations.flat_map do |attempt, records|
+          records.map { |record| { attempt: attempt, **record }.freeze }
+        end.freeze
+      end
+
       # :raise => WorkflowError(message); :return_last => state.candidate;
       # callable => mode.call(state). Default :raise preserves legacy
       # behavior for hosts that don't opt in to graceful exits.
@@ -125,21 +212,34 @@ module Smith
       # evaluator sees the same seed_messages + inject_state context.
       # Default nil keeps the legacy candidate-only payload.
       def build_evaluator_input(state)
-        return [{ role: :user, content: state.candidate.to_s }] unless state.config[:evaluator_context] == :inject_state
+        content = candidate_content(state.candidate)
+        return [{ role: :user, content: }] unless state.config[:evaluator_context] == :inject_state
 
         prior = Array(state.prepared_input).dup
-        prior.push(role: :user, content: state.candidate.to_s)
+        prior.push(role: :user, content:)
+      end
+
+      # A structured candidate (an output_schema agent's Hash or Array) gets
+      # the JSON serialisation the provider boundary applies; text stays as is.
+      def candidate_content(candidate)
+        candidate.is_a?(Hash) || candidate.is_a?(Array) ? json_message_content(candidate) : candidate.to_s
       end
 
       # Runs after candidate generation, before evaluator invocation.
-      # Receives (state, @context); @context is mutable. Return value
-      # is discarded. Raised exceptions bubble through the standard
-      # step failure path.
-      def invoke_before_eval(state)
+      # Receives (state, @context); @context is mutable. A returned Hash
+      # whose accept (Symbol or String key) is false is the round's
+      # evaluation, validated like evaluator output, and the evaluator is
+      # not called; any other return value is discarded. Raised exceptions
+      # bubble through the standard step failure path.
+      def before_eval_rejection(state)
         callback = state.config[:before_eval]
         return unless callback
 
-        callback.call(state, @context)
+        verdict = callback.call(state, @context)
+        return unless verdict.is_a?(Hash)
+
+        evaluation = normalize_evaluation(verdict)
+        evaluation if evaluation.key?(:accept) && evaluation[:accept].equal?(false)
       end
 
       def invoke_with_evaluator_schema(evaluator_class, schema, input)
@@ -193,7 +293,7 @@ module Smith
         return prepared_input if round.zero?
 
         (prepared_input&.dup || []).push(
-          { role: :assistant, content: prior_candidate.to_s },
+          { role: :assistant, content: candidate_content(prior_candidate) },
           {
             role: :user,
             content: "[smith:refinement-round] #{round + 1}\n[smith:evaluator-feedback]\n#{feedback}"

data/lib/smith/workflow/event_integration.rb

@@ -15,7 +15,54 @@ module Smith
           Events::StepCompleted.new(
             transition: transition.name.to_sym,
             from: transition.from&.to_sym,
-            to: transition.to.to_sym
+            to: transition.to.to_sym,
+            workflow: Attribution.ambient.workflow
+          )
+        )
+      end
+
+      # Failure-path counterpart to emit_step_completed, fired from both
+      # failure handlers before they branch or re-raise, so an observer sees
+      # exactly where execution went dark. Classification reuses
+      # FailureRecord's bounded taxonomy; raw messages are never emitted. The
+      # rescue keeps a broken instrument from altering failure semantics:
+      # the original error, not an emission error, must win.
+      def emit_step_failed(step)
+        failure = FailureRecord.capture(step)
+        record_failed_transition_trace(failure)
+        emit_step_failed_event(failure)
+      rescue StandardError => e
+        Smith.config.logger&.error("Smith failed-step emission error: #{e.message}")
+      end
+
+      # `outcome`, not `result`: `result` is a reserved content key in the
+      # trace pipeline (it carries tool results and is stripped by the
+      # default content policy). Matches the :provider_call vocabulary.
+      # `from`/`to` stay present even when nil, matching the success-trace
+      # shape: an absent key would let the ambient attribution of an
+      # enclosing scope (a parent step's `from`) show through the
+      # fields-under-data merge and fabricate a foreign state fact.
+      def record_failed_transition_trace(failure)
+        data = {
+          transition: failure[:transition], from: failure[:from], to: failure[:to],
+          outcome: :failed,
+          error_class: failure[:error_class],
+          error_family: failure[:error_family]
+        }
+        data[:retryable] = failure[:error_retryable] unless failure[:error_retryable].nil?
+        Smith::Trace.record(type: :transition, data: data)
+      end
+
+      def emit_step_failed_event(failure)
+        Smith::Events.emit(
+          Events::StepFailed.new(
+            transition: DiagnosticText.capture(failure[:transition].to_s, max_bytes: 256).to_sym,
+            from: failure[:from]&.to_sym,
+            to: failure[:to]&.to_sym,
+            error_class: failure[:error_class],
+            error_family: failure[:error_family],
+            retryable: failure[:error_retryable],
+            workflow: Attribution.ambient.workflow
           )
         )
       end

data/lib/smith/workflow/execution.rb

@@ -31,6 +31,12 @@ module Smith
       end
 
       def execute_step_body(transition)
+        # Reset the per-step agent-attribution carrier so only a serial agent
+        # step that actually runs (below) leaves model/provider for complete_step;
+        # a deterministic step never sets it and must not inherit a stale value.
+        # The optimizer's verdict carrier resets for the same reason.
+        @pending_agent_execution = nil
+        @pending_evaluations = nil
         output = with_scoped_artifacts { run_with_retry_policy(transition) }
         StepCompletion.instance_method(:complete_step).bind_call(self, transition, output)
       end
@@ -93,6 +99,10 @@ module Smith
         begin
           result = execute_transition_body(transition, prepared_input: prepared_input)
           agent_result = result.is_a?(AgentResult) ? result : nil
+          # Capture the model/provider that actually served this serial agent
+          # step (post fallback resolution) for complete_step to fold into the
+          # durable step record. Nil when no agent ran (e.g. unconfigured model).
+          @pending_agent_execution = agent_result && { model: agent_result.model_used, provider: agent_result.provider_used }
           reconcile_branch_budget(ledger, reserved, agent_result: agent_result)
           reserved = nil
           agent_result ? agent_result.content : result

data/lib/smith/workflow/failure_reconstructor.rb

@@ -18,6 +18,9 @@ module Smith
         "bounded_completion_error" => ->(record) { Smith::BoundedCompletionError.new(record[:error_message]) },
         "persisted_failure_invalid" => ->(record) { Smith::PersistedFailureInvalid.new(record[:error_message]) },
         "deadline_exceeded" => ->(record) { Smith::DeadlineExceeded.new(record[:error_message]) },
+        "provider_permanent_failure" => ->(record) { provider_permanent_failure(record) },
+        "budget_exceeded" => ->(record) { Smith::BudgetExceeded.new(record[:error_message]) },
+        "guardrail_failed" => ->(record) { Smith::GuardrailFailed.new(record[:error_message]) },
         "agent_error" => ->(record) { Smith::AgentError.new(record[:error_message]) },
         "workflow_error" => ->(record) { Smith::WorkflowError.new(record[:error_message]) },
         "other" => ->(record) { RuntimeError.new(record[:error_message]) }
@@ -25,7 +28,8 @@ module Smith
       SPECIAL_CLASS_BUILDERS = {
         "Smith::Workflow::Composite::BranchFailure" => lambda { |record|
           Smith::Workflow::Composite::BranchFailure.from_details(record[:error_details])
-        }
+        },
+        "Smith::BlankAgentOutputError" => ->(record) { blank_agent_output_failure(record) }
       }.freeze
       private_constant :FAMILY_BUILDERS, :SPECIAL_CLASS_BUILDERS
 
@@ -73,7 +77,19 @@ module Smith
         Smith::ToolFailureNotificationFailed.from_details(record.fetch(:error_details))
       end
 
-      private_class_method :deterministic_step_failure, :tool_guardrail_failure, :tool_failure_notification_failure
+      def self.provider_permanent_failure(record)
+        Smith::ProviderPermanentFailure.from_details(record.fetch(:error_details), message: record[:error_message])
+      end
+
+      def self.blank_agent_output_failure(record)
+        details = record[:error_details]
+        return Smith::AgentError.new(record[:error_message]) if details.nil?
+
+        Smith::BlankAgentOutputError.from_details(details)
+      end
+
+      private_class_method :deterministic_step_failure, :tool_guardrail_failure, :tool_failure_notification_failure,
+                           :provider_permanent_failure, :blank_agent_output_failure
     end
   end
 end

data/lib/smith/workflow/failure_record.rb

@@ -20,6 +20,9 @@ module Smith
         [Smith::PersistedFailureInvalid, "persisted_failure_invalid"],
         [Smith::ToolGuardrailFailed, "tool_guardrail_failed"],
         [Smith::DeadlineExceeded, "deadline_exceeded"],
+        [Smith::ProviderPermanentFailure, "provider_permanent_failure"],
+        [Smith::BudgetExceeded, "budget_exceeded"],
+        [Smith::GuardrailFailed, "guardrail_failed"],
         [Smith::AgentError, "agent_error"],
         [Smith::WorkflowError, "workflow_error"]
       ].freeze
@@ -27,10 +30,7 @@ module Smith
       EXCEPTION_CAUSE = Exception.instance_method(:cause)
       EXCEPTION_MESSAGE = Exception.instance_method(:message)
       MODULE_MATCH = Module.instance_method(:===)
-      MODULE_NAME = Module.instance_method(:name)
-      OBJECT_CLASS = Object.instance_method(:class)
-      private_constant :ERROR_FAMILIES, :BOOLEAN_VALUES, :EXCEPTION_CAUSE, :EXCEPTION_MESSAGE, :MODULE_MATCH,
-                       :MODULE_NAME, :OBJECT_CLASS
+      private_constant :ERROR_FAMILIES, :BOOLEAN_VALUES, :EXCEPTION_CAUSE, :EXCEPTION_MESSAGE, :MODULE_MATCH
 
       extend Dry::Initializer
 
@@ -52,7 +52,7 @@ module Smith
 
       def error_attributes(error)
         {
-          error_class: DiagnosticText.capture(error_class_name(error), max_bytes: 512),
+          error_class: DiagnosticText.error_class_name(error),
           error_family: error_family(error),
           error_message: error_message(error),
           error_retryable: retryable_value(error),
@@ -70,7 +70,7 @@ module Smith
       def cause_attributes(error)
         cause = uncertainty_cause(error)
         {
-          error_cause_class: cause && DiagnosticText.capture(error_class_name(cause), max_bytes: 512),
+          error_cause_class: cause && DiagnosticText.error_class_name(cause),
           error_cause_family: cause && error_family(cause),
           error_cause_message: cause && error_message(cause)
         }
@@ -89,11 +89,6 @@ module Smith
         ERROR_FAMILIES.find { |error_class, _| MODULE_MATCH.bind_call(error_class, error) }&.last || "other"
       end
 
-      def error_class_name(error)
-        error_class = OBJECT_CLASS.bind_call(error)
-        MODULE_NAME.bind_call(error_class) || "anonymous_error"
-      end
-
       # Never captures blank text: restore requires non-empty messages, so
       # a blank live message takes the shared deterministic placeholder.
       def error_message(error)

data/lib/smith/workflow/failure_record_validator.rb

@@ -20,14 +20,25 @@ module Smith
         "Smith::AgentError" => "agent_error",
         "Smith::BlankAgentOutputError" => "agent_error",
         "Smith::DeadlineExceeded" => "deadline_exceeded",
+        "Smith::ProviderPermanentFailure" => "provider_permanent_failure",
+        "Smith::BudgetExceeded" => "budget_exceeded",
+        "Smith::GuardrailFailed" => "guardrail_failed",
         "Smith::WorkflowError" => "workflow_error",
         "Smith::UnresolvedTransitionError" => "workflow_error",
         "Smith::Workflow::Composite::BranchFailure" => "workflow_error"
       }.freeze
+      # Records written before these classes had their own families carry
+      # "other" and no details; they keep restoring exactly as they did.
+      LEGACY_ERROR_FAMILIES = {
+        "Smith::ProviderPermanentFailure" => "other",
+        "Smith::BudgetExceeded" => "other",
+        "Smith::GuardrailFailed" => "other"
+      }.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
+        deadline_exceeded provider_permanent_failure budget_exceeded guardrail_failed agent_error workflow_error
+        other
       ].freeze
       RETRY_FORBIDDEN_FAMILIES = %w[
         tool_capture_failed tool_failure_notification_failed tool_outcome_uncertain tool_execution_not_admitted
@@ -40,11 +51,15 @@ module Smith
         },
         "Smith::Workflow::Composite::BranchFailure" => lambda { |details|
           Smith::Workflow::Composite::BranchFailure.from_details(details)
+        },
+        "Smith::ProviderPermanentFailure" => ->(details) { Smith::ProviderPermanentFailure.from_details(details) },
+        "Smith::BlankAgentOutputError" => lambda { |details|
+          Smith::BlankAgentOutputError.from_details(details) unless details.nil?
         }
       }.freeze
       BOOLEAN_VALUES = [true, false].freeze
-      private_constant :KNOWN_ERROR_FAMILIES, :KNOWN_FAMILIES, :RETRY_FORBIDDEN_FAMILIES, :DETAIL_VALIDATORS,
-                       :BOOLEAN_VALUES
+      private_constant :KNOWN_ERROR_FAMILIES, :LEGACY_ERROR_FAMILIES, :KNOWN_FAMILIES, :RETRY_FORBIDDEN_FAMILIES,
+                       :DETAIL_VALIDATORS, :BOOLEAN_VALUES
 
       extend Dry::Initializer
 
@@ -74,10 +89,13 @@ module Smith
       def validate_class_family!
         expected = KNOWN_ERROR_FAMILIES[snapshot[:error_class]]
         return unless expected && family != expected
+        return if legacy_family?
 
         reject!("persisted workflow failure class and family disagree")
       end
 
+      def legacy_family? = LEGACY_ERROR_FAMILIES[snapshot[:error_class]] == family
+
       def validate_retry_policy!
         forbidden = snapshot[:error_retry_forbidden]
         return if forbidden.nil?
@@ -103,6 +121,8 @@ module Smith
       end
 
       def validate_details!
+        return if legacy_family?
+
         validator = DETAIL_VALIDATORS[snapshot[:error_class]]
         validator&.call(snapshot[:error_details])
       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/guardrail_integration.rb

@@ -24,6 +24,14 @@ module Smith
 
       def handle_step_failure(transition, error)
         step = { transition: transition.name, from: transition.from, to: transition.to, error: error }
+        fold_pending_evaluations(step)
+        @pending_evaluations = nil
+        # 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 +58,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/optimization_state.rb

@@ -3,10 +3,10 @@
 module Smith
   class Workflow
     OptimizationState = Struct.new(
-      :config, :prepared_input, :candidate, :feedback, :last_score, :generator_class, :evaluator_class
+      :config, :prepared_input, :candidate, :feedback, :last_score, :generator_class, :evaluator_class, :evaluations
     ) do
       def initialize(config, prepared_input)
-        super(config, prepared_input, nil, nil, nil, nil, nil)
+        super(config, prepared_input, nil, nil, nil, nil, nil, [].freeze)
       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
@@ -95,6 +99,13 @@ 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 and @pending_evaluations are
+        # 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
+        @pending_evaluations = 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
@@ -150,16 +161,17 @@ module Smith
 
         raise Smith::StepInProgressOnRestore.new(
           workflow: self.class.name,
-          persistence_key: normalized[:persistence_key]
+          persistence_key: normalized[:persistence_key],
+          state: normalized[:state],
+          transition: normalized[:next_transition_name]
         )
       end
 
       def validate_raw_step_in_progress!(state)
         return unless state.is_a?(Hash)
 
-        marker = state[:step_in_progress] || state["step_in_progress"]
-        persistence_key = state[:persistence_key] || state["persistence_key"]
-        validate_step_in_progress!(step_in_progress: marker, persistence_key:)
+        fields = %i[step_in_progress persistence_key state next_transition_name]
+        validate_step_in_progress!(fields.to_h { |field| [field, state[field] || state[field.to_s]] })
       end
 
       def validate_seed_digest!(normalized)
@@ -192,6 +204,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
@@ -204,6 +227,19 @@ 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)
+
+        execution = symbolize_keys(value)
+        execution[:provider] = execution[:provider].to_sym if execution[:provider].is_a?(String)
+        execution
+      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
@@ -398,7 +434,20 @@ module Smith
         config = self.class.budget
         return nil unless config
 
-        Budget::Ledger.new(limits: config, consumed: consumed)
+        Budget::Ledger.new(limits: config, consumed: declared_budget_consumed(consumed, config))
+      end
+
+      # A dimension the workflow no longer declares has no limit, so its
+      # consumed entry (a key an earlier version accepted and ignored) is
+      # dropped rather than refused.
+      def declared_budget_consumed(consumed, config)
+        return consumed unless consumed.is_a?(Hash)
+
+        declared = config.each_key.to_h { |dimension| [dimension.to_s, dimension] }
+        consumed.each_with_object({}) do |(key, amount), kept|
+          dimension = declared[key.to_s]
+          kept[dimension] = amount if dimension
+        end
       end
 
       def persisted_context

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

@@ -5,14 +5,18 @@ module Smith
     module RetryExecution
       private
 
+      # `@step_attempt` is the attempt under way, from 1, which the optimizer
+      # names its verdicts by; transient, set here before every attempt.
       def run_with_retry_policy(transition)
         config = transition.retry_config
+        @step_attempt = 1
         return run_guarded_step(transition) unless config
 
         schedule = retry_schedule(config)
         attempt = 0
         begin
           attempt += 1
+          @step_attempt = attempt
           run_guarded_step(transition)
         rescue StandardError => e
           raise unless retry_transition_error?(config, e, attempt)