pgbus 0.20.1 → 0.21.1

data/lib/pgbus/client.rb

@@ -720,16 +720,24 @@ module Pgbus
     # reaper to determine if a uniqueness lock with msg_id=0 (placeholder)
     # still has a corresponding queue message.
     #
-    # +queue_name+ may be either a logical name (e.g. "default") or an already
-    # prefixed physical name (e.g. "pgbus_default"). The client normalizes both.
+    # +queue_name+ is a logical name (e.g. "default"), expanded through the
+    # queue strategy, unless the caller passes +prefixed: false+ for a physical
+    # table name (e.g. "pgbus_default_p1"), used as is. The name's spelling
+    # decides nothing: a logical "pgbus_mailers" lives in pgbus_pgbus_mailers
+    # (issue #569).
     #
     # Returns:
     #   true  — the message definitely exists in the queue
     #   false — the message definitely does not exist
     #   nil   — could not determine (e.g. queue table missing or unknown error).
     #           Callers MUST treat nil as "exists" for safety.
-    def message_in_queue?(queue_name, msg_id:)
-      message_exists?(queue_name, msg_id: msg_id)
+    #
+    # Under priority routing a logical name probes every `_pN` table, and each
+    # table has its own msg_id sequence: a bare +msg_id+ may match a different
+    # message in a sibling sub-queue. A caller that knows the sub-queue passes
+    # its physical name with +prefixed: false+.
+    def message_in_queue?(queue_name, msg_id:, prefixed: true)
+      message_exists?(queue_name, msg_id: msg_id, prefixed: prefixed)
     end
 
     # Look up a queue row by ActiveJob job_id in the JSON payload. Used by the
@@ -738,10 +746,10 @@ module Pgbus
     #
     # Same tri-state as message_exists?: true / false / nil (unknown). A
     # logical name expands to every physical table the strategy owns (the
-    # `_pN` sub-queues under priority routing); an already-prefixed physical
-    # name probes itself only.
-    def message_with_job_id?(queue_name, job_id:)
-      tables = lookup_physical_queue_names(queue_name).map { |name| QueueNameValidator.sanitize!(name) }
+    # `_pN` sub-queues under priority routing); a physical name passed with
+    # +prefixed: false+ probes itself only.
+    def message_with_job_id?(queue_name, job_id:, prefixed: true)
+      tables = lookup_physical_queue_names(queue_name, prefixed: prefixed).map { |name| QueueNameValidator.sanitize!(name) }
       determined = false
 
       synchronized do
@@ -758,43 +766,85 @@ module Pgbus
       determined ? false : nil # rubocop:disable Style/ReturnNilInPredicateMethodDefinition -- tri-state: nil means unknown
     end
 
-    # DLQ companion of a logical or already-physical queue name. Does not
-    # re-prefix a name that resolve_full_queue_name already expanded.
-    def dead_letter_physical_name(queue_name)
-      full = resolve_full_queue_name(queue_name)
+    # The physical table that holds message +msg_id+, or nil when none does.
+    # See locate_messages.
+    def locate_message(queue_name, msg_id:, job_id: nil, prefixed: true)
+      locate_messages(queue_name, [[msg_id, job_id]], prefixed: prefixed)[msg_id.to_i]
+    end
+
+    # { msg_id => physical table } for each [msg_id, job_id] pair whose
+    # message is queued, one query per table on one connection. A logical
+    # name expands to every table the strategy owns, and under priority
+    # routing each `_pN` sub-queue numbers its messages from its own
+    # sequence: only a message carrying the pair's job_id matches, or any
+    # message with that msg_id when job_id is nil, the first table winning
+    # (issue #577). A physical name with +prefixed: false+ is probed alone.
+    # A table that does not exist holds nothing; other errors raise.
+    def locate_messages(queue_name, messages, prefixed: true)
+      wanted = messages.to_h { |msg_id, job_id| [msg_id.to_i, job_id&.to_s] }
+      tables = lookup_physical_queue_names(queue_name, prefixed: prefixed)
+      located = {}
+
+      synchronized do
+        with_raw_connection do |conn|
+          tables.each do |name|
+            pending = wanted.keys - located.keys
+            break if pending.empty?
+
+            queued_job_ids(conn, QueueNameValidator.sanitize!(name), pending).each do |row|
+              msg_id = row["msg_id"].to_i
+              job_id = wanted[msg_id]
+              located[msg_id] ||= name if job_id.nil? || row["job_id"] == job_id
+            end
+          end
+        end
+      end
+
+      located
+    end
+
+    # DLQ companion of a logical queue name, or of a physical table name passed
+    # with +prefixed: false+.
+    def dead_letter_physical_name(queue_name, prefixed: true)
+      return config.dead_letter_queue_name(queue_name) if prefixed
+
       # Priority sub-queues share the logical queue's DLQ (`pgbus_default_dlq`),
-      # not a per-priority `…_pN_dlq`. Only strip when the strategy actually
-      # creates `_pN` tables — a logical queue named `orders_p0` must keep it.
-      base = @queue_strategy.priority? ? full.sub(/_p\d+\z/, "") : full
+      # not a per-priority `…_pN_dlq`. Only a physical name can be a sub-queue,
+      # and only when the strategy actually creates `_pN` tables: a logical
+      # queue named `orders_p0` keeps its suffix.
+      name = queue_name.to_s
+      base = @queue_strategy.priority? ? name.sub(/_p\d+\z/, "") : name
       "#{base}#{Pgbus::DEAD_LETTER_SUFFIX}"
     end
 
     # Same tri-state as message_exists?: true / false / nil (unknown).
-    def message_archived?(queue_name, msg_id:)
-      full_name = resolve_full_queue_name(queue_name)
-      sanitized = QueueNameValidator.sanitize!(full_name)
+    # A logical name probes the archive of every physical table the strategy
+    # owns, like message_exists?; a physical name (prefixed: false) its own.
+    # A bare msg_id is unique per table only (see message_in_queue?).
+    def message_archived?(queue_name, msg_id:, prefixed: true)
+      tables = lookup_physical_queue_names(queue_name, prefixed: prefixed).map { |name| QueueNameValidator.sanitize!(name) }
+      determined = false
 
       synchronized do
         with_raw_connection do |conn|
-          msg_id_archived?(conn, sanitized, msg_id.to_i)
+          tables.each do |sanitized|
+            archived = probe_archive_presence(conn, sanitized, msg_id.to_i)
+            return true if archived == true
+
+            determined = true unless archived == :missing
+          end
         end
       end
-    rescue ActiveRecord::StatementInvalid => e
-      raise unless undefined_table_error?(e)
-
-      nil
-    rescue StandardError => e
-      raise unless defined?(PG::UndefinedTable) && e.is_a?(PG::UndefinedTable)
 
-      nil
+      determined ? false : nil # rubocop:disable Style/ReturnNilInPredicateMethodDefinition -- tri-state: nil means unknown
     end
 
-    def message_exists?(queue_name, msg_id: nil, uniqueness_key: nil)
+    def message_exists?(queue_name, msg_id: nil, uniqueness_key: nil, prefixed: true)
       has_msg_id = !msg_id.nil?
       has_uniqueness_key = !uniqueness_key.nil?
       raise ArgumentError, "pass msg_id, uniqueness_key, or both" unless has_msg_id || has_uniqueness_key
 
-      tables = lookup_physical_queue_names(queue_name).map { |name| QueueNameValidator.sanitize!(name) }
+      tables = lookup_physical_queue_names(queue_name, prefixed: prefixed).map { |name| QueueNameValidator.sanitize!(name) }
       determined = false
 
       synchronized do
@@ -1092,21 +1142,10 @@ module Pgbus
       end
     end
 
-    # Accept either a logical name ("default") or an already-prefixed
-    # physical name ("pgbus_default") and return the physical name.
-    # Coerces symbols to strings so callers can pass either form.
-    def resolve_full_queue_name(queue_name)
-      name = queue_name.to_s
-      prefix = "#{config.queue_prefix}_"
-      name.start_with?(prefix) ? name : config.queue_name(name)
-    end
-
     # Logical names expand through QueueFactory so a priority queue's _pN
-    # tables are included; already-prefixed physical names stay as-is.
-    def lookup_physical_queue_names(queue_name)
-      name = queue_name.to_s
-      prefix = "#{config.queue_prefix}_"
-      name.start_with?(prefix) ? [name] : @queue_strategy.physical_queue_names(name)
+    # tables are included; a physical name (prefixed: false) stays as is.
+    def lookup_physical_queue_names(queue_name, prefixed:)
+      prefixed ? @queue_strategy.physical_queue_names(queue_name.to_s) : [queue_name.to_s]
     end
 
     def probe_queue_presence(conn, sanitized, msg_id:, uniqueness_key:)
@@ -1125,6 +1164,18 @@ module Pgbus
       :missing
     end
 
+    def probe_archive_presence(conn, sanitized, msg_id)
+      msg_id_archived?(conn, sanitized, msg_id)
+    rescue ActiveRecord::StatementInvalid => e
+      raise unless undefined_table_error?(e)
+
+      :missing
+    rescue StandardError => e
+      raise unless defined?(PG::UndefinedTable) && e.is_a?(PG::UndefinedTable)
+
+      :missing
+    end
+
     def probe_job_id_presence(conn, sanitized, job_id)
       job_id_present?(conn, sanitized, job_id)
     rescue ActiveRecord::StatementInvalid => e
@@ -1137,6 +1188,22 @@ module Pgbus
       :missing
     end
 
+    # msg_ids are integers, so the array literal is safe.
+    def queued_job_ids(conn, sanitized, msg_ids)
+      conn.exec_params(
+        "SELECT msg_id, message::jsonb ->> 'job_id' AS job_id FROM pgmq.q_#{sanitized} WHERE msg_id = ANY($1::bigint[])",
+        ["{#{msg_ids.join(",")}}"]
+      )
+    rescue ActiveRecord::StatementInvalid => e
+      raise unless undefined_table_error?(e)
+
+      []
+    rescue StandardError => e
+      raise unless defined?(PG::UndefinedTable) && e.is_a?(PG::UndefinedTable)
+
+      []
+    end
+
     def scan_uniqueness_keys(conn, sanitized, keys, found)
       placeholders = keys.each_index.map { |i| "$#{i + 1}" }.join(", ")
       result = conn.exec_params(

data/lib/pgbus/configuration/workflow_settings.rb

@@ -12,7 +12,7 @@ module Pgbus
     #   config.workflow_max_payload_size = 131_072      # bytes: arguments and step outputs
     #   config.workflow_error_backtrace_lines = 50      # backtrace lines kept on a failed step
     #   config.workflow_waiting_visibility_threshold = 7.days # a step waiting this long without a
-    #                                                   # wait_timeout: counts as stuck (waiting_overdue)
+    #                                                   # deadline counts as stuck (waiting_overdue)
     #   config.workflow_subject_url = ->(type, id) { "/admin/#{type.underscore.pluralize}/#{id}" }
     #                                                   # the dashboard's subject link (nil: plain text)
     module WorkflowSettings

data/lib/pgbus/mcp/tools/workflow_stats_tool.rb

@@ -11,7 +11,7 @@ module Pgbus
         tool_name "pgbus_workflow_stats"
         title "Pgbus Workflow Stats"
         description <<~DESC
-          One Pgbus::Workflow class over a window (1h, 24h default, 7d or 30d, capped at workflow_retention). steps, in declaration order (gravestones as kind "removed"; names only the rows hold as declared: false): counts (runs sitting at the step now by run status ready/performing/waiting/paused), run_ms (p50/p95/p99 of finished_at - started_at over completed or failed attempts) and pickup_ms (p50/p95 of scheduled → started), rates (failed: an error was recorded, reattempted, skipped) and outcomes over the sample_size attempts that finished in the window; percentiles over fewer than 20 samples are noisy. Also: started/finished/cancelled, e2e_ms, duration_histogram (finished runs per created → finished range), throughput (runs started/finished/cancelled per bucket_seconds), funnel (of the runs started in the window: reached = runs with a row for the step, stopped = where each run is now by status) and by_revision (the five app revisions that finished an attempt last, newest first, totals and per step).
+          One Pgbus::Workflow class over a window (1h, 24h default, 7d or 30d, capped at workflow_retention). steps, in declaration order (gravestones as kind "removed"; names only the rows hold as declared: false): wait_timeout (a wait_for: step's wait_timeout: in seconds, "dynamic" when a lambda or a method name sets it per run, null without one), counts (runs sitting at the step now by run status ready/performing/waiting/paused), run_ms (p50/p95/p99 of finished_at - started_at over completed or failed attempts) and pickup_ms (p50/p95 of scheduled → started), rates (failed: an error was recorded, reattempted, skipped) and outcomes over the sample_size attempts that finished in the window; percentiles over fewer than 20 samples are noisy. Also: started/finished/cancelled, e2e_ms, duration_histogram (finished runs per created → finished range), throughput (runs started/finished/cancelled per bucket_seconds), funnel (of the runs started in the window: reached = runs with a row for the step, stopped = where each run is now by status) and by_revision (the five app revisions that finished an attempt last, newest first, totals and per step).
         DESC
 
         input_schema(

data/lib/pgbus/mcp/tools/workflows_attention_tool.rb

@@ -9,7 +9,7 @@ module Pgbus
         tool_name "pgbus_workflows_attention"
         title "Pgbus Workflows Needing Attention"
         description <<~DESC
-          Ongoing Pgbus::Workflow runs that need a person, grouped by (workflow_class, step_name, reason, error_class): reason is paused_error, stalled, paused_manual, overdue (due but not picked up past workflow_stall_threshold) or waiting_overdue (waiting past workflow_waiting_visibility_threshold without a wait_timeout). Each group has its run count, first_seen_at/last_seen_at, the status its runs are in and the actions that status allows; total_runs sums the groups (at most 200 groups, biggest first). workflow_class narrows them to one class. The newest error message is redacted unless the server allows payloads and include_payloads is set.
+          Ongoing Pgbus::Workflow runs that need a person, grouped by (workflow_class, step_name, reason, error_class): reason is paused_error, stalled, paused_manual, overdue (due but not picked up past workflow_stall_threshold) or waiting_overdue (waiting past workflow_waiting_visibility_threshold without a deadline: no wait_timeout, or a per-run one that set none or cleared it after a :notify notice). Each group has its run count, first_seen_at/last_seen_at, the status its runs are in and the actions that status allows; total_runs sums the groups (at most 200 groups, biggest first). workflow_class narrows them to one class. The newest error message is redacted unless the server allows payloads and include_payloads is set.
         DESC
 
         input_schema(

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.20.1"
+  VERSION = "0.21.1"
 end

data/lib/pgbus/web/data_source/workflow_list.rb

@@ -158,12 +158,14 @@ module Pgbus
           end
         end
 
-        # { step_id => the first deadline its wait missed } for waiting steps
-        # with a deadline, one query: the first wait_timed_out event of each.
+        # { step_id => the first deadline its wait missed } for steps waiting
+        # on a signal, one query: the first wait_timed_out event of each.
         # Only on_timeout: :notify leaves a step waiting after that event
-        # (issue #565): every other on_timeout ends the attempt.
+        # (issue #565): every other on_timeout ends the attempt. A per-run
+        # wait_timeout: may have cleared the deadline at that notice (issue
+        # #574), so a step without one is looked up too.
         def late_since(waiting)
-          steps = waiting.select { |step| step_attribute(step, :timeout_at) }
+          steps = waiting.select { |step| step_attribute(step, :wait_for) }
           return {} if steps.empty?
 
           WorkflowEvent.where(workflow_id: steps.map(&:workflow_id), step_id: steps.map(&:id),

data/lib/pgbus/web/data_source.rb

@@ -299,9 +299,9 @@ module Pgbus
         # duplicate (the original is still in the queue waiting for retry).
         # Falls back to enqueueing a fresh copy only if the original is gone
         # (e.g., already moved to DLQ).
-        msg_id = event["msg_id"]
-        if msg_id && @client.message_exists?(event["queue_name"], msg_id: msg_id.to_i)
-          @client.set_visibility_timeout(event["queue_name"], msg_id.to_i, vt: 0)
+        physical = failed_message_queue(event)
+        if physical
+          @client.set_visibility_timeout(physical, event["msg_id"].to_i, vt: 0, prefixed: false)
         else
           payload = JSON.parse(event["payload"])
           headers = event["headers"]
@@ -1721,12 +1721,29 @@ module Pgbus
         nil
       end
 
+      # The physical queue holding a failed job's message, or nil when it is
+      # gone. The row records the logical queue only, and under priority
+      # routing a msg_id repeats across the _pN sub-queues, so the job's
+      # job_id must match too (issue #577). Two sub-queues' failures with the
+      # same msg_id share one row, which keeps the first one's payload: that
+      # is the message found (issue #583).
+      def failed_message_queue(event)
+        return unless event["queue_name"] && event["msg_id"]
+
+        @client.locate_message(event["queue_name"], msg_id: event["msg_id"].to_i, job_id: failed_job_id(event))
+      end
+
+      def failed_job_id(event)
+        payload = event["payload"]
+        payload = JSON.parse(payload) if payload.is_a?(String)
+        payload["job_id"] if payload.is_a?(Hash)
+      end
+
       # Archive the queue message a failed_event row points to. Idempotent —
       # silently no-ops if the message no longer exists in the queue.
       def archive_failed_message(event)
-        return unless event["queue_name"] && event["msg_id"]
-
-        @client.archive_message(event["queue_name"], event["msg_id"].to_i)
+        physical = failed_message_queue(event)
+        @client.archive_message(physical, event["msg_id"].to_i, prefixed: false) if physical
       rescue StandardError => e
         Pgbus.logger.debug do
           "[Pgbus::Web] Error archiving message for failed event #{event["id"]}: #{e.message}"
@@ -1734,30 +1751,30 @@ module Pgbus
       end
 
       # Archive every queue message referenced by a failed_event row.
-      # Groups by queue and uses archive_batch so an N-event discard is
-      # one SQL statement per queue instead of N per-row roundtrips.
-      # Falls back to per-row archive inside a rescue if a batch fails,
-      # so one bad queue can't block progress on the others.
+      # Groups by queue, then locates and archive_batches per physical table,
+      # so an N-event discard is two SQL statements per table instead of N
+      # per-row roundtrips. Falls back to per-row archive inside a rescue if
+      # a batch fails, so one bad queue can't block progress on the others.
       def archive_all_failed_messages
         rows = connection.select_all(
-          "SELECT id, queue_name, msg_id FROM pgbus_failed_events WHERE msg_id IS NOT NULL AND #{NOT_HANDLER_QUEUE}",
+          "SELECT id, queue_name, msg_id, payload FROM pgbus_failed_events WHERE msg_id IS NOT NULL AND #{NOT_HANDLER_QUEUE}",
           "Pgbus Collect Failed Messages", [handler_queue_names_literal]
         )
 
         grouped = rows.to_a.group_by { |row| row["queue_name"] }
         grouped.each do |queue_name, events|
-          msg_ids = events.filter_map { |row| row["msg_id"]&.to_i }
-          next if msg_ids.empty?
-
-          begin
-            @client.archive_batch(queue_name, msg_ids)
-          rescue StandardError => e
-            Pgbus.logger.debug do
-              "[Pgbus::Web] archive_batch failed for #{queue_name} (#{e.message}); " \
-                "falling back to per-row archive"
-            end
-            events.each { |row| archive_failed_message(row) }
+          # A priority queue's msg_ids repeat across its _pN sub-queues, so
+          # each message is located first and archived from its own table.
+          located = @client.locate_messages(queue_name, events.map { |row| [row["msg_id"].to_i, failed_job_id(row)] })
+          located.group_by { |_msg_id, physical| physical }.each do |physical, pairs|
+            @client.archive_batch(physical, pairs.map(&:first), prefixed: false)
+          end
+        rescue StandardError => e
+          Pgbus.logger.debug do
+            "[Pgbus::Web] archive_batch failed for #{queue_name} (#{e.message}); " \
+              "falling back to per-row archive"
           end
+          events.each { |row| archive_failed_message(row) }
         end
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error archiving failed messages: #{e.message}" }

data/lib/pgbus/web/workflow_insights_report.rb

@@ -47,14 +47,14 @@ module Pgbus
         )
       end
 
-      # [{ name:, kind:, removed:, declared: }] in pipeline order.
+      # [{ name:, kind:, removed:, declared:, wait_timeout: }] in pipeline order.
       def step_list(klass, stats, ongoing, reached, stopped)
         seen = (stats.keys + ongoing.map { |row| row[:step] } + reached.keys + stopped.keys.map(&:first)).compact.uniq
         declared = klass ? klass.workflow_steps.entries.map { |entry| declared_step(entry) } : []
         extra = (seen - declared.map { |entry| entry[:name] }).sort_by do |name|
           [reached.dig(name, :position) || Float::INFINITY, stats.dig(name, :first_seen_at)&.to_f || Float::INFINITY, name]
         end
-        declared + extra.map { |name| { name: name, kind: nil, removed: false, declared: false } }
+        declared + extra.map { |name| { name: name, kind: nil, removed: false, declared: false, wait_timeout: nil } }
       end
 
       def declared_step(entry)
@@ -63,7 +63,15 @@ module Pgbus
                elsif entry.waits_for_signal? then "signal"
                else "step"
                end
-        { name: entry.name, kind: kind, removed: entry.removed?, declared: true }
+        { name: entry.name, kind: kind, removed: entry.removed?, declared: true, wait_timeout: wait_timeout(entry) }
+      end
+
+      # A signal step's wait_timeout: in seconds, "dynamic" for a per-run one
+      # (issue #574), nil without one.
+      def wait_timeout(entry)
+        return nil if entry.removed?
+
+        entry.dynamic_wait_timeout? ? "dynamic" : entry.wait_timeout
       end
 
       def step(entry, stats, ongoing)

data/lib/pgbus/web/workflow_state.rb

@@ -51,9 +51,12 @@ module Pgbus
         return ["waiting", "waiting_step", { step: step }] unless row[:waiting_for]
 
         args = { signal: row[:waiting_for], ago: row[:waiting_since] }
-        return ["waiting", "waiting_signal", args] unless row[:timeout_at]
+        return signal_deadline(row, args.merge(time: row[:timeout_at])) if row[:timeout_at]
+        # A per-run wait_timeout: reported once under on_timeout: :notify,
+        # then left without a deadline (issue #574).
+        return ["waiting", "waiting_signal_late_no_deadline", args.merge(late: row[:late_since])] if row[:late_since]
 
-        signal_deadline(row, args.merge(time: row[:timeout_at]))
+        ["waiting", "waiting_signal", args]
       end
 
       # An on_timeout: :notify deadline sends a late notice and the wait goes

data/lib/pgbus/workflow/instance.rb

@@ -94,6 +94,33 @@ module Pgbus
         @timed_out == true
       end
 
+      # Inside a step (its guards and its body): true when this attempt holds
+      # a signal before its gate runs: signal! woke the step, or an earlier
+      # attempt of it took one and reattempted or failed into a pause. False
+      # on an attempt that has not waited yet (even one whose gate then takes
+      # a buffered signal), after an on_timeout: :run wake, and in a step
+      # without wait_for:. The same answer for the whole attempt.
+      def woken?
+        step_context!(:woken?)
+        @woken = !@signal_peek&.held.nil? if @woken.nil?
+        @woken
+      end
+
+      # Inside a step (its guards and its body): true when the gate runs this
+      # attempt with a signal: the one it holds (woken?), or a pending one its
+      # wait_for: matcher takes. The guard for "skip a wait the record already
+      # passed", which neither skips a signalled step nor leaves its signal
+      # pending. False after an on_timeout: :run wake (the gate takes no
+      # signal then) and in a step without wait_for:. Reads only: the gate
+      # claims the signal after the guards.
+      #
+      #   step :await_shipped, skip_if: -> { subject.shipped? && !signal_ready? }, wait_for: :shipped do … end
+      def signal_ready?
+        step_context!(:signal_ready?)
+        @signal_ready = !@signal_peek&.ready.nil? if @signal_ready.nil?
+        @signal_ready
+      end
+
       # Deliver a signal to this run. Stored under the run's lock; a step
       # waiting for it (wait_for:) is woken at once, otherwise it waits,
       # pending, for the step that claims it. With an idempotency_key a
@@ -164,19 +191,25 @@ module Pgbus
         @guarding = false
       end
 
-      # Used by the StepJob only.
-      def enter_step(context)
+      # Used by the StepJob only. +signals+ is the attempt's SignalPeek, which
+      # woken? and signal_ready? read until the gate answers them.
+      def enter_step(context, signals: nil)
         @step_context = context
+        @signal_peek = signals
         @output_values = nil
         @pending_output = nil
         @received_signal = nil
         @timed_out = false
+        @woken = nil
+        @signal_ready = nil
       end
 
       # Used by the StepJob's signal gate only.
-      def enter_wait(signal:, timed_out:)
+      def enter_wait(signal:, timed_out:, woken: false)
         @received_signal = signal
         @timed_out = timed_out
+        @woken = woken
+        @signal_ready = !signal.nil?
       end
     end
   end

data/lib/pgbus/workflow/runner.rb

@@ -68,11 +68,11 @@ module Pgbus
 
       # --- start! and rerun! --------------------------------------------
 
-      def start(klass, subject:, arguments:, idempotency_key: nil)
+      def start(klass, subject:, arguments:, idempotency_key: nil, actor: DEFAULT_ACTOR, reason: nil)
         attrs = run_attributes(klass, idempotency_key: idempotency_key)
                 .merge(Payload.subject_attributes(subject))
                 .merge(arguments: Payload.dump(arguments, what: "arguments of #{klass.name}"))
-        insert_run(klass, attrs, actor: DEFAULT_ACTOR)
+        insert_run(klass, attrs, actor: actor, reason: reason)
       end
 
       # A finished or cancelled run started again: same subject and

data/lib/pgbus/workflow/signal_peek.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # What a wait_for: step's attempt holds and what its gate would run it
+    # with (issue #572), read without claiming anything. The StepJob builds
+    # one per attempt: the step readers woken? and signal_ready? read it in
+    # the guards, and the gate decides with the same one, so the gate takes
+    # exactly the signal signal_ready? promised. All of it runs under the
+    # run's row lock, so each answer is looked up (and a matcher run) once.
+    class SignalPeek
+      def initialize(record, step, definition, now: Time.current)
+        @record = record
+        @step = step
+        @definition = definition
+        @now = now
+      end
+
+      # The claimed signal the step holds (signal! woke it, or an earlier
+      # attempt took one and reattempted or paused), or nil. Always nil for a
+      # step without wait_for:.
+      def held
+        return @held if defined?(@held)
+
+        @held = waits? ? WorkflowSignal.held_by_step(@record.workflow_id, @step.step_name) : nil
+      end
+
+      # The sweep woke this attempt with on_timeout: :run: its body runs
+      # without a signal (Signals.timed_out?).
+      def timed_out? = Signals.timed_out?(@step, @now)
+
+      # The signal the gate runs this attempt with: the one the step holds,
+      # else the oldest pending one its matcher takes. nil when the wait timed
+      # out (the body runs without one), when nothing matches (the step
+      # parks), and for a step without wait_for:.
+      def ready
+        return @ready if defined?(@ready)
+
+        @ready = waits? && !timed_out? ? held || Signals.match(@record, @definition.wait_for) : nil
+      end
+
+      private
+
+      def waits? = @definition.waits_for_signal?
+    end
+  end
+end

data/lib/pgbus/workflow/signals.rb

@@ -12,6 +12,8 @@ module Pgbus
     # lock: a signal this step already holds (woken by signal!, or claimed by
     # an earlier attempt that reattempted or paused on a failure), else the
     # oldest pending one its matcher takes, else the step parks as waiting.
+    # The guards run first; woken? and signal_ready? (issue #572) show them
+    # what the gate holds and would take, through SignalPeek, claiming nothing.
     #
     # A claimed signal is consumed when its step ends, except when that
     # attempt reattempts or fails into a pause: the next attempt runs with it.
@@ -38,23 +40,38 @@ module Pgbus
       end
 
       # The gate of a wait_for: step. True when the body runs (with a signal,
-      # or timed out), false when the step parked. Sets received_signal and
-      # timed_out? on +workflow+.
-      def gate(record, step, definition, workflow, now: Time.current)
-        if timed_out?(step, now)
+      # or timed out), false when the step parked. Sets received_signal,
+      # timed_out?, woken? and signal_ready? on +workflow+. Which signal it
+      # takes is SignalPeek#ready: given the attempt's +peek+ (the StepJob
+      # passes the one its guards read), the very answer signal_ready? gave.
+      def gate(record, step, definition, workflow, now: Time.current, peek: nil)
+        peek ||= SignalPeek.new(record, step, definition, now: now)
+        if peek.timed_out?
           workflow.send(:enter_wait, signal: nil, timed_out: true)
           return true
         end
 
-        signal = WorkflowSignal.held_by_step(record.workflow_id, step.step_name) || match(record, definition.wait_for)
-        return park(record, step, definition, now) unless signal
+        signal = peek.ready
+        return park(record, step, definition, workflow, now) unless signal
 
+        woken = !peek.held.nil?
         claim!(record, step, signal, actor: Runner::SYSTEM_ACTOR) if signal.status == "pending"
         step.update_columns(signal_id: signal.id) unless step.signal_id == signal.id
-        workflow.send(:enter_wait, signal: signal, timed_out: false)
+        workflow.send(:enter_wait, signal: signal, timed_out: false, woken: woken)
         true
       end
 
+      # An attempt that ended before its gate (cancel_if, skip_if, a guard
+      # that raised, a removed_step) records +held+, the signal the step
+      # holds, on its row, so settle treats it as for any attempt: consumed
+      # when the step ends, kept when it reattempts or fails into a pause. A
+      # post-reattempt row carries no signal_id until its gate runs. A
+      # pending signal stays pending: no step took it, and a later wait_for:
+      # step may.
+      def adopt_held(step, held)
+        step.update_columns(signal_id: held.id) if held && step.signal_id != held.id
+      end
+
       # The step's attempt ended (StepOutcome.apply): consume the signal it
       # holds, unless the next attempt runs with it.
       def settle(step, status, column, now:)
@@ -116,14 +133,18 @@ module Pgbus
         nil
       end
 
-      def park(record, step, definition, now) # rubocop:disable Naming/PredicateMethod -- the gate's false: the body does not run
-        timeout_at = definition.wait_timeout && (now + definition.wait_timeout)
+      # A per-run wait_timeout: is evaluated here, before Waiting.park! writes
+      # the waiting state: one that raises (an invalid return raises
+      # ArgumentError) leaves the attempt in_progress for the step's exception
+      # policies; nil parks it without a deadline.
+      def park(record, step, definition, workflow, now) # rubocop:disable Naming/PredicateMethod -- the gate's false: the body does not run
+        timeout_at = definition.timeout_at_for(workflow, now)
         Waiting.park!(record, step, now: now, wait_for: definition.wait_for_name, timeout_at: timeout_at)
         false
       end
 
       # This attempt waited, holds no signal, and its wait_timeout passed: the
-      # sweep woke it with on_timeout: :run.
+      # sweep woke it with on_timeout: :run (SignalPeek#timed_out?).
       def timed_out?(step, now)
         !step.waiting_since.nil? && step.signal_id.nil? && !step.timeout_at.nil? && step.timeout_at <= now + 1
       end