pgbus 0.14.0 → 0.14.2

data/lib/pgbus/client.rb

@@ -339,6 +339,10 @@ module Pgbus
       end
     end
 
+    def target_queue(queue_name, priority = nil)
+      @queue_strategy.target_queue(queue_name, priority)
+    end
+
     def send_message(queue_name, payload, headers: nil, delay: 0, priority: nil)
       target = @queue_strategy.target_queue(queue_name, priority)
       Instrumentation.instrument("pgbus.client.send_message", queue: target) do
@@ -381,13 +385,17 @@ module Pgbus
       msg_id
     end
 
-    def send_batch(queue_name, payloads, headers: nil, delay: 0)
-      full_name = config.queue_name(queue_name)
+    # Bulk enqueue. Routes through the queue strategy exactly like
+    # #send_message: under priority routing the bare `pgbus_<queue>` table is
+    # never created (only `_p0.._pN` are), so targeting it raised
+    # PG::UndefinedTable and no worker would have read it either.
+    def send_batch(queue_name, payloads, headers: nil, delay: 0, priority: nil)
+      target = @queue_strategy.target_queue(queue_name, priority)
       serialized, serialized_headers = serialize_batch(payloads, headers)
-      Instrumentation.instrument("pgbus.client.send_batch", queue: full_name, size: payloads.size) do
+      Instrumentation.instrument("pgbus.client.send_batch", queue: target, size: payloads.size) do
         with_stale_connection_retry do
           ensure_queue(queue_name)
-          synchronized { @pgmq.produce_batch(full_name, serialized, headers: serialized_headers, delay: delay) }
+          synchronized { @pgmq.produce_batch(target, serialized, headers: serialized_headers, delay: delay) }
         end
       end
     end
@@ -682,21 +690,55 @@ module Pgbus
     #   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_exists?(queue_name, msg_id: nil, uniqueness_key: nil)
-      has_msg_id = !msg_id.nil?
-      has_uniqueness_key = !uniqueness_key.nil?
-      raise ArgumentError, "pass exactly one of msg_id or uniqueness_key" unless has_msg_id ^ has_uniqueness_key
+    def message_in_queue?(queue_name, msg_id:)
+      message_exists?(queue_name, msg_id: msg_id)
+    end
+
+    # Look up a queue row by ActiveJob job_id in the JSON payload. Used by the
+    # batch sweep: move_to_dead_letter produces a new DLQ msg_id, so the
+    # source msg_id is not a DLQ identity.
+    #
+    # 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) }
+      determined = false
+
+      synchronized do
+        with_raw_connection do |conn|
+          tables.each do |sanitized|
+            present = probe_job_id_presence(conn, sanitized, job_id)
+            return true if present == true
+
+            determined = true unless present == :missing
+          end
+        end
+      end
 
+      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)
+      # 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
+      "#{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)
 
       synchronized do
         with_raw_connection do |conn|
-          if has_msg_id
-            msg_id_present?(conn, sanitized, msg_id.to_i)
-          else
-            uniqueness_key_present?(conn, sanitized, uniqueness_key)
-          end
+          msg_id_archived?(conn, sanitized, msg_id.to_i)
         end
       end
     rescue ActiveRecord::StatementInvalid => e
@@ -709,6 +751,64 @@ module Pgbus
       nil
     end
 
+    def message_exists?(queue_name, msg_id: nil, uniqueness_key: nil)
+      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) }
+      determined = false
+
+      synchronized do
+        with_raw_connection do |conn|
+          tables.each do |sanitized|
+            present = probe_queue_presence(
+              conn, sanitized,
+              msg_id: has_msg_id ? msg_id.to_i : nil,
+              uniqueness_key: has_uniqueness_key ? uniqueness_key : nil
+            )
+            return true if present == true
+
+            determined = true unless present == :missing
+          end
+        end
+      end
+
+      determined ? false : nil # rubocop:disable Style/ReturnNilInPredicateMethodDefinition -- tri-state: nil means unknown
+    end
+
+    # Which uniqueness keys currently appear in any live PGMQ queue payload.
+    # Used by the dispatcher reaper for unbound locks (pending / msg_id=0)
+    # so it never probes the synthetic `pending` queue (issue #418).
+    #
+    # Per-queue UndefinedTable is skipped (table dropped between listing and
+    # select). Failure to list pgmq.meta — or any non-undefined error — raises;
+    # callers must treat that as "unknown" and keep the lock.
+    def uniqueness_keys_present(lock_keys)
+      keys = Array(lock_keys).compact.map(&:to_s).uniq
+      return Set.new if keys.empty?
+
+      found = Set.new
+      synchronized do
+        with_raw_connection do |conn|
+          names = conn.exec("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
+                      .map { |row| row["queue_name"] }
+          names.each do |name|
+            break if found.size == keys.size
+
+            sanitized = begin
+              QueueNameValidator.sanitize!(name)
+            rescue ArgumentError
+              next
+            end
+
+            scan_uniqueness_keys(conn, sanitized, keys, found)
+          end
+        end
+      end
+      found
+    end
+
     def purge_archive(queue_name, older_than:, batch_size: 1000)
       full_name = config.queue_name(queue_name)
       sanitized = QueueNameValidator.sanitize!(full_name)
@@ -933,9 +1033,76 @@ module Pgbus
       name.start_with?(prefix) ? name : config.queue_name(name)
     end
 
-    def msg_id_present?(conn, sanitized, msg_id)
+    # 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)
+    end
+
+    def probe_queue_presence(conn, sanitized, msg_id:, uniqueness_key:)
+      if msg_id
+        msg_id_present?(conn, sanitized, msg_id, uniqueness_key: uniqueness_key)
+      else
+        uniqueness_key_present?(conn, sanitized, uniqueness_key)
+      end
+    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
+      raise unless undefined_table_error?(e)
+
+      :missing
+    rescue StandardError => e
+      raise unless defined?(PG::UndefinedTable) && e.is_a?(PG::UndefinedTable)
+
+      :missing
+    end
+
+    def scan_uniqueness_keys(conn, sanitized, keys, found)
+      placeholders = keys.each_index.map { |i| "$#{i + 1}" }.join(", ")
       result = conn.exec_params(
-        "SELECT 1 FROM pgmq.q_#{sanitized} WHERE msg_id = $1 LIMIT 1",
+        "SELECT DISTINCT message::jsonb ->> 'pgbus_uniqueness_key' AS k " \
+        "FROM pgmq.q_#{sanitized} " \
+        "WHERE message::jsonb ->> 'pgbus_uniqueness_key' IN (#{placeholders})",
+        keys
+      )
+      result.each { |row| found.add(row["k"]) if row["k"] }
+    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 msg_id_present?(conn, sanitized, msg_id, uniqueness_key: nil)
+      result = if uniqueness_key
+                 conn.exec_params(
+                   "SELECT 1 FROM pgmq.q_#{sanitized} WHERE msg_id = $1 " \
+                   "AND message::jsonb ->> 'pgbus_uniqueness_key' = $2 LIMIT 1",
+                   [msg_id, uniqueness_key]
+                 )
+               else
+                 conn.exec_params(
+                   "SELECT 1 FROM pgmq.q_#{sanitized} WHERE msg_id = $1 LIMIT 1",
+                   [msg_id]
+                 )
+               end
+      result.ntuples.positive?
+    end
+
+    def msg_id_archived?(conn, sanitized, msg_id)
+      result = conn.exec_params(
+        "SELECT 1 FROM pgmq.a_#{sanitized} WHERE msg_id = $1 LIMIT 1",
         [msg_id]
       )
       result.ntuples.positive?
@@ -950,6 +1117,15 @@ module Pgbus
       result.ntuples.positive?
     end
 
+    def job_id_present?(conn, sanitized, job_id)
+      result = conn.exec_params(
+        "SELECT 1 FROM pgmq.q_#{sanitized} " \
+        "WHERE message::jsonb ->> 'job_id' = $1 LIMIT 1",
+        [job_id]
+      )
+      result.ntuples.positive?
+    end
+
     # Detect "relation does not exist" via the underlying PG error type.
     # Falls back to message matching only if PG::UndefinedTable is undefined
     # (very old pg gem) — never relies on locale-sensitive text.

data/lib/pgbus/concurrency/blocked_execution.rb

@@ -28,12 +28,25 @@ module Pgbus
         # otherwise. This avoids losing a blocked row if enqueue fails.
         def promote_next(concurrency_key, client:, delay: 0)
           released = nil
+          msg_id = nil
           Pgbus::BlockedExecution.transaction do
             released = release_next(concurrency_key)
             raise ActiveRecord::Rollback unless released
 
             actual_delay = resolve_delay(released[:payload], delay)
-            client.send_message(released[:queue_name], released[:payload], delay: actual_delay)
+            # Carry the enqueuer's priority through: under priority routing it
+            # picks the _pN sub-queue, not just the release order (issue #423).
+            msg_id = client.send_message(released[:queue_name], released[:payload],
+                                         delay: actual_delay, priority: released[:priority])
+          end
+
+          if released && msg_id
+            begin
+              Batch.backfill_execution(released[:payload], msg_id,
+                                       client.target_queue(released[:queue_name], released[:priority]))
+            rescue StandardError => e
+              Pgbus.logger.warn { "[Pgbus] Batch execution backfill failed after promote: #{e.message}" }
+            end
           end
 
           !!released

data/lib/pgbus/configuration.rb

@@ -75,6 +75,12 @@ module Pgbus
     # Pgbus::Process::Dispatcher.
     attr_reader :archive_retention
 
+    # Batch execution-row sweep + finished-batch cleanup. Retention nil disables
+    # cleanup (same sentinel as archive_retention). Sweep interval is required.
+    # Stall threshold: how long a pending batch may go without a new execution
+    # row (or an orphan row without a msg_id) before the sweep repairs it.
+    attr_reader :batch_retention, :batch_sweep_interval, :batch_stall_threshold
+
     # Transactional outbox
     attr_accessor :outbox_enabled, :outbox_poll_interval, :outbox_batch_size
     attr_reader :outbox_retention # rubocop:disable Style/AccessorGrouping
@@ -264,6 +270,9 @@ module Pgbus
       @group_mode = nil
 
       @archive_retention = 7 * 24 * 3600 # 7 days
+      @batch_retention = 7 * 24 * 3600 # 7 days
+      @batch_sweep_interval = 300 # 5 minutes
+      @batch_stall_threshold = 300 # 5 minutes, solid_queue's stalled_for default
 
       @outbox_enabled = false
       @outbox_poll_interval = 1.0
@@ -818,7 +827,9 @@ module Pgbus
 
       # Interval knobs: positive Numeric, never nil (mirror polling_interval).
       { dispatch_interval: dispatch_interval, outbox_poll_interval: outbox_poll_interval,
-        recurring_schedule_interval: recurring_schedule_interval }.each do |name, value|
+        recurring_schedule_interval: recurring_schedule_interval,
+        batch_sweep_interval: batch_sweep_interval,
+        batch_stall_threshold: batch_stall_threshold }.each do |name, value|
         raise Pgbus::ConfigurationError, "#{name} must be > 0" unless value.is_a?(Numeric) && value.positive?
       end
 
@@ -1170,6 +1181,18 @@ module Pgbus
       @archive_retention = coerce_duration!(value, :archive_retention)
     end
 
+    def batch_retention=(value)
+      @batch_retention = coerce_duration!(value, :batch_retention)
+    end
+
+    def batch_sweep_interval=(value)
+      @batch_sweep_interval = coerce_duration!(value, :batch_sweep_interval)
+    end
+
+    def batch_stall_threshold=(value)
+      @batch_stall_threshold = coerce_duration!(value, :batch_stall_threshold)
+    end
+
     def outbox_retention=(value)
       @outbox_retention = coerce_duration!(value, :outbox_retention)
     end

data/lib/pgbus/engine.rb

@@ -74,6 +74,7 @@ module Pgbus
       ActiveSupport.on_load(:active_job) do
         include Pgbus::Concurrency
         include Pgbus::Uniqueness
+        include Pgbus::ActiveJob::BatchId
       end
     end
 

data/lib/pgbus/generators/migration_detector.rb

@@ -78,6 +78,8 @@ module Pgbus
         add_recurring: "pgbus:add_recurring",
         add_failed_events_index: "pgbus:add_failed_events_index",
         add_processed_event_completion: "pgbus:add_processed_event_completion",
+        add_batch_executions: "pgbus:add_batch_executions",
+        add_batch_callback_jobs: "pgbus:add_batch_callback_jobs",
         tune_autovacuum: "pgbus:tune_autovacuum",
         tune_fillfactor: "pgbus:tune_fillfactor"
       }.freeze
@@ -97,6 +99,8 @@ module Pgbus
         add_recurring: "recurring tasks + executions tables",
         add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)",
         add_processed_event_completion: "completed_at on pgbus_processed_events (two-phase idempotency claim)",
+        add_batch_executions: "batch execution-row tracking (self-healing completion, on_failure rename)",
+        add_batch_callback_jobs: "batch callback-job columns (configured ActiveJob instances as batch callbacks)",
         tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables",
         tune_fillfactor: "fillfactor=70 on PGMQ queue tables (reduces page density during update churn)"
       }.freeze
@@ -123,6 +127,8 @@ module Pgbus
           *recurring_migrations,
           *failed_events_index_migrations,
           *processed_event_completion_migrations,
+          *batch_executions_migrations,
+          *batch_callback_jobs_migrations,
           *autovacuum_migrations,
           *fillfactor_migrations
         ]
@@ -223,6 +229,30 @@ module Pgbus
         [:add_processed_event_completion]
       end
 
+      # Execution-row tracking plus the on_discard → on_failure column rename
+      # ship as one upgrade. Either a missing executions table or leftover
+      # pre-rename columns means this generator still needs to run.
+      def batch_executions_migrations
+        return [] unless table_exists?("pgbus_batches")
+
+        batches_columns = column_names("pgbus_batches")
+        migrated = table_exists?("pgbus_batch_executions") &&
+                   batches_columns.include?("on_failure_class") &&
+                   !batches_columns.include?("discarded_jobs")
+        return [] if migrated
+
+        [:add_batch_executions]
+      end
+
+      # Configured callback instances (on_finish: MyJob.new.set(...)) need
+      # somewhere to store the serialized job — issue #415.
+      def batch_callback_jobs_migrations
+        return [] unless table_exists?("pgbus_batches")
+        return [] if column_names("pgbus_batches").include?("on_finish_job")
+
+        [:add_batch_callback_jobs]
+      end
+
       # Autovacuum tuning: check if any PGMQ queue table already has
       # custom autovacuum settings applied. If not, queue the migration.
       def autovacuum_migrations

data/lib/pgbus/instrumentation.rb

@@ -25,6 +25,11 @@ module Pgbus
   #   pgbus.consumer.recycle       — consumer hit a recycle threshold (same payload shape as pgbus.worker.recycle)
   #   pgbus.serializer.serialize   — job/event serialization
   #   pgbus.serializer.deserialize — job/event deserialization
+  #   pgbus.batch_finished         — batch flipped to finished
+  #                                  payload: batch_id, total_jobs, completed_jobs, failed_jobs
+  #   pgbus.batch_sweep            — dispatcher stalled-batch sweep
+  #                                  payload: stalled_for, stale_executions, orphan_rows,
+  #                                  started_batches, finished_batches
   #
   module Instrumentation
     module_function

data/lib/pgbus/outbox/poller.rb

@@ -102,12 +102,12 @@ module Pgbus
         return 0 if entries.empty?
 
         succeeded = 0
-        entries.group_by { |e| [e.queue_name, e.priority, e.delay || 0] }.each do |(queue, _priority, delay), group|
+        entries.group_by { |e| [e.queue_name, e.priority, e.delay || 0] }.each do |(queue, priority, delay), group|
           payloads = group.map(&:payload)
           headers = group.map(&:headers)
           headers = nil if headers.all?(&:blank?)
 
-          Pgbus.client.send_batch(queue, payloads, headers: headers, delay: delay)
+          Pgbus.client.send_batch(queue, payloads, headers: headers, delay: delay, priority: priority)
           now = Time.current
           group.each { |e| e.update!(published_at: now) }
           succeeded += group.size
@@ -119,16 +119,15 @@ module Pgbus
         succeeded
       end
 
-      # Fallback for individual publishing when a batch fails.
-      # Intentionally omits priority to match send_batch routing behavior
-      # (base queue only), ensuring consistent queue placement regardless
-      # of whether the batch or fallback path is used.
+      # Fallback for individual publishing when a batch fails. Passes the same
+      # priority as the batch path so queue placement is identical either way.
       def publish_single_queue(entry)
         Pgbus.client.send_message(
           entry.queue_name,
           entry.payload,
           headers: entry.headers,
-          delay: entry.delay || 0
+          delay: entry.delay || 0,
+          priority: entry.priority
         )
         entry.update!(published_at: Time.current)
         true

data/lib/pgbus/process/dispatcher.rb

@@ -51,6 +51,7 @@ module Pgbus
       # Enumerated so set_maintenance_timestamp can validate its argument.
       MAINTENANCE_TIMESTAMPS = %i[
         @last_cleanup_at @last_reap_at @last_concurrency_at @last_batch_cleanup_at
+        @last_batch_sweep_at
         @last_recurring_cleanup_at @last_archive_compaction_at @last_stream_archive_compaction_at
         @last_outbox_cleanup_at @last_job_lock_cleanup_at @last_stats_cleanup_at
         @last_orphan_stream_sweep_at @last_table_maintenance_at
@@ -107,7 +108,7 @@ module Pgbus
 
       # Test seam: set one of the @last_*_at maintenance timestamps so a task
       # becomes (or stops being) due on the next run_maintenance. The timestamps
-      # are per-task monotonic clocks with no constructor injection point (all 12
+      # are per-task monotonic clocks with no constructor injection point (all
       # default to monotonic_now at construction), so a post-construction setter
       # is the minimal way to drive the due/not-due logic deterministically.
       # ivar must be one of the recognized @last_*_at names.
@@ -233,6 +234,7 @@ module Pgbus
         results << run_if_due(now, :@last_reap_at, REAP_INTERVAL) { reap_stale_processes }
         results << run_if_due(now, :@last_concurrency_at, CONCURRENCY_INTERVAL) { cleanup_concurrency }
         results << run_if_due(now, :@last_batch_cleanup_at, BATCH_CLEANUP_INTERVAL) { cleanup_batches }
+        results << run_if_due(now, :@last_batch_sweep_at, config.batch_sweep_interval) { sweep_stalled_batches }
         results << run_if_due(now, :@last_recurring_cleanup_at, RECURRING_CLEANUP_INTERVAL) { cleanup_recurring_executions }
         results << run_if_due(now, :@last_archive_compaction_at, ARCHIVE_COMPACTION_INTERVAL) { compact_archives }
         results << run_if_due(now, :@last_stream_archive_compaction_at, ARCHIVE_COMPACTION_INTERVAL) { prune_stream_archives }
@@ -373,13 +375,23 @@ module Pgbus
       end
 
       def cleanup_batches
-        deleted = Batch.cleanup(older_than: Time.current - (7 * 24 * 3600)) # 7 days
+        retention = config.batch_retention
+        return unless retention&.positive?
+
+        deleted = Batch.cleanup(older_than: Time.current - retention)
         Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} finished batches" } if deleted.positive?
       rescue StandardError => e
         log_maintenance_failure("Batch cleanup", e)
         e
       end
 
+      def sweep_stalled_batches
+        Batch.sweep_stalled
+      rescue StandardError => e
+        log_maintenance_failure("Batch sweep", e)
+        e
+      end
+
       def cleanup_stats
         retention = config.stats_retention
         return unless retention&.positive?
@@ -446,34 +458,46 @@ module Pgbus
         # younger could be a freshly-acquired lock whose send_message hasn't
         # committed yet.
         threshold = Time.current - (config.visibility_timeout * 2)
+        candidates = keys.select { |key| key.created_at && key.created_at < threshold && key.queue_name }
+        return 0 if candidates.empty?
 
-        orphaned = keys.select do |key|
-          next false unless key.created_at && key.created_at < threshold
-          next false unless key.queue_name
-
-          message_gone?(key)
-        end
+        bound, unbound = candidates.partition { |key| bound_lock?(key) }
+        orphaned = bound.select { |key| message_gone?(key) }
+        orphaned.concat(gone_unbound_locks(unbound))
 
         return 0 if orphaned.empty?
 
         UniquenessKey.where(lock_key: orphaned.map(&:lock_key)).delete_all
       end
 
-      # Returns true if the message referenced by this lock is definitely gone
-      # from the queue. Returns false otherwise (message present, or unknown).
+      def bound_lock?(key)
+        !Uniqueness.placeholder?(queue_name: key.queue_name, msg_id: key.msg_id)
+      end
+
+      # Unbound rows (synthetic "pending" queue and/or msg_id=0) must not probe
+      # pgmq.q_<prefix>_pending — that table does not exist, message_exists?
+      # returns nil, and the reaper would keep the lock forever (issue #418).
+      # Scan every live queue for the payload key instead.
+      def gone_unbound_locks(unbound)
+        return [] if unbound.empty?
+
+        present = Pgbus.client.uniqueness_keys_present(unbound.map(&:lock_key))
+        unbound.reject { |key| present.include?(key.lock_key) }
+      end
+
+      # Returns true if the message referenced by this bound lock is definitely
+      # gone from the queue. Returns false otherwise (message present, or unknown).
       #
       # Routes through Pgbus::Client#message_exists? so all PGMQ access stays
       # behind the client interface. The client returns nil when it can't
       # determine the answer (queue table missing, etc.); we treat that as
       # "still here" — the reaper must NEVER delete a lock when in doubt.
       def message_gone?(key)
-        msg_id = key.msg_id.to_i
-        result = if msg_id.positive?
-                   Pgbus.client.message_exists?(key.queue_name, msg_id: msg_id)
-                 else
-                   Pgbus.client.message_exists?(key.queue_name, uniqueness_key: key.lock_key)
-                 end
-
+        result = Pgbus.client.message_exists?(
+          key.queue_name,
+          msg_id: key.msg_id.to_i,
+          uniqueness_key: key.lock_key
+        )
         result == false
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Reap check failed for #{key.lock_key}: #{e.message}" }

data/lib/pgbus/recurring/schedule.rb

@@ -29,7 +29,8 @@ module Pgbus
           payload = inject_uniqueness_metadata(task, payload)
 
           Pgbus.client.ensure_queue(queue)
-          Pgbus.client.send_message(queue, payload, headers: headers)
+          msg_id = Pgbus.client.send_message(queue, payload, headers: headers)
+          bind_uniqueness_lock(acquired_key, queue, msg_id)
 
           Pgbus.logger.info do
             "[Pgbus] Enqueued recurring task #{task.key} (#{task.class_name || task.command}) " \
@@ -159,6 +160,16 @@ module Pgbus
         :already_locked # Fail closed — skip enqueue when lock check errors
       end
 
+      # Point the pre-produce lock at the real PGMQ msg_id. Fail-soft: a bind
+      # error must not roll back an already-produced message (issue #418).
+      def bind_uniqueness_lock(key, queue, msg_id)
+        return unless key.is_a?(String)
+
+        Uniqueness.bind_lock(key, queue_name: queue, msg_id: msg_id)
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness bind failed: #{e.message}" }
+      end
+
       # Release a uniqueness lock. Safe to call with nil or :already_locked.
       def release_uniqueness_lock(key)
         return if key.nil? || key == :already_locked

data/lib/pgbus/uniqueness.rb

@@ -10,9 +10,10 @@ module Pgbus
   # at any time — from enqueue through completion.
   #
   # Lock lifecycle (advisory lock + thin lookup table):
-  #   1. Enqueue: pg_advisory_xact_lock serializes concurrent attempts,
-  #      then INSERT INTO pgbus_uniqueness_keys ON CONFLICT DO NOTHING.
-  #      The lock row lives as long as the job is in the queue or executing.
+  #   1. Enqueue: INSERT INTO pgbus_uniqueness_keys ON CONFLICT DO NOTHING
+  #      (logical queue, msg_id=0). After send_message, bind! writes the
+  #      real msg_id. The lock row lives as long as the job is in the queue
+  #      or executing.
   #   2. Execution: PGMQ's visibility timeout is the execution lock —
   #      no separate claim_for_execution step needed.
   #   3. Completion/DLQ: DELETE FROM pgbus_uniqueness_keys WHERE lock_key = ?.
@@ -43,6 +44,10 @@ module Pgbus
 
     METADATA_KEY = "pgbus_uniqueness_key"
     STRATEGY_KEY = "pgbus_uniqueness_strategy"
+    # Synthetic queue stored before produce when the caller does not know the
+    # real queue yet. Never a live PGMQ queue — the reaper must not probe
+    # pgmq.q_<prefix>_pending for these rows (issue #418).
+    PLACEHOLDER_QUEUE = "pending"
 
     VALID_STRATEGIES = %i[until_executed while_executing].freeze
     VALID_CONFLICTS = %i[reject discard log].freeze
@@ -174,19 +179,25 @@ module Pgbus
                      UniquenessKey.acquire!(key, queue_name: queue_name, msg_id: msg_id)
                    else
                      # Pre-produce check: use advisory lock + ON CONFLICT
-                     UniquenessKey.acquire!(key, queue_name: queue_name || "pending", msg_id: msg_id || 0)
+                     UniquenessKey.acquire!(key, queue_name: queue_name || PLACEHOLDER_QUEUE, msg_id: msg_id || 0)
                    end
         acquired ? :acquired : :locked
       end
 
       # Acquire the uniqueness lock at execution time (:while_executing only).
       # Returns true if acquired, false if another instance is running.
-      def acquire_execution_lock(key, payload)
+      #
+      # Bound to the message being executed so a row left behind by a crashed
+      # attempt of the SAME message is re-acquired on retry instead of locking
+      # that message out until it dead-letters (issue #423). Callers without a
+      # message (legacy signature) fall back to the unbound placeholder.
+      def acquire_execution_lock(key, payload, msg_id: 0, queue_name: nil)
         strategy = extract_strategy(payload)
         return true unless strategy == :while_executing
 
-        queue_name = payload["queue_name"] || "unknown"
-        UniquenessKey.acquire!(key, queue_name: queue_name, msg_id: 0)
+        queue_name ||= payload["queue_name"] || "unknown"
+        UniquenessKey.acquire!(key, queue_name: queue_name, msg_id: msg_id.to_i,
+                                    reacquire_same_message: msg_id.to_i.positive?)
       end
 
       # Release the uniqueness lock after execution completes.
@@ -195,6 +206,23 @@ module Pgbus
 
         UniquenessKey.release!(key)
       end
+
+      # Point a pre-produce lock at the real queue + PGMQ msg_id after send.
+      # No-op when key is nil or msg_id is not a positive integer (the reaper
+      # treats those rows as unbound and scans live queues instead).
+      def bind_lock(key, queue_name:, msg_id:)
+        return unless key
+        return unless msg_id.to_i.positive?
+
+        UniquenessKey.bind!(key, queue_name: queue_name, msg_id: msg_id)
+      end
+
+      # True when the uniqueness row is not yet bound to a real PGMQ message.
+      # Covers the synthetic pending queue and any msg_id=0 placeholder
+      # (recurring scheduler, bind-not-yet-run, bind failure).
+      def placeholder?(queue_name:, msg_id:)
+        msg_id.to_i <= 0 || queue_name.to_s == PLACEHOLDER_QUEUE
+      end
     end
   end
 end