pgbus 0.20.0 → 0.20.1

data/config/locales/it.yml

@@ -1349,6 +1349,8 @@ it:
         unknown_html: 'Stato: %{status}.'
         waiting_batch_html: In attesa del lotto %{batch} (%{done} lavori su %{total} completati).
         waiting_signal_html: In attesa del segnale %{signal} da %{ago}.
+        waiting_signal_late_html: In attesa del segnale %{signal} da %{ago} (in ritardo da %{late}). Il prossimo avviso di ritardo parte %{time}.
+        waiting_signal_notify_html: In attesa del segnale %{signal} da %{ago}. Un avviso di ritardo parte %{time} e l'attesa continua.
         waiting_signal_timeout_html: In attesa del segnale %{signal} da %{ago}. L'attesa scade %{time}.
         waiting_step_html: In attesa di %{step}.
       not_found:
@@ -1451,7 +1453,7 @@ it:
         ready: Pronti
         waiting: In attesa
       timeline:
-        caption: 'Ogni tentativo, il più vecchio in alto: atteso (la sua attesa), in coda (previsto, non ancora preso), eseguito (colorato in base a come è finito) e in attesa (di un segnale o del suo lotto), con le pause su una riga a parte. La tabella dei tentativi qui sotto riporta le stesse durate.'
+        caption: 'Ogni tentativo, il più vecchio in alto: atteso (la sua attesa), in coda (previsto, non ancora preso), eseguito (colorato in base a come è finito) e in attesa (di un segnale o del suo lotto), con le pause su una riga a parte. La tabella dei tentativi qui sotto riporta le stesse durate. Una linea tratteggiata segna ogni volta che un''attesa ha superato la scadenza.'
         empty: Ancora nessun tentativo.
         paused_period_html: In pausa dalle %{from} per %{duration}
         paused_row: In pausa
@@ -1465,3 +1467,4 @@ it:
           waited: Atteso
           waiting: In attesa
         title: Cronologia
+        wait_timeout_html: 'L''attesa di %{step} ha superato la scadenza alle %{time} (on_timeout: %{action}).'

data/config/locales/ja.yml

@@ -1349,6 +1349,8 @@ ja:
         unknown_html: 'ステータス: %{status}。'
         waiting_batch_html: バッチ %{batch} を待機中です（%{total} 件中 %{done} 件のジョブが完了）。
         waiting_signal_html: シグナル %{signal} を %{ago} から待機中です。
+        waiting_signal_late_html: シグナル %{signal} を %{ago} から待機中です（%{late} から遅延）。次の遅延通知は %{time} に送られます。
+        waiting_signal_notify_html: シグナル %{signal} を %{ago} から待機中です。遅延通知は %{time} に送られ、待機は続きます。
         waiting_signal_timeout_html: シグナル %{signal} を %{ago} から待機中です。待機は %{time} にタイムアウトします。
         waiting_step_html: "%{step} を待機中です。"
       not_found:
@@ -1451,7 +1453,7 @@ ja:
         ready: 実行待ち
         waiting: 待機中
       timeline:
-        caption: 各試行を古い順に表示します。待機（待ち時間）、キュー（期限到来、未取得）、実行（終了状態で色分け）、待機中（シグナルまたはバッチ待ち）で、一時停止は別の行に表示します。下の試行テーブルにも同じ時間が載っています。
+        caption: 各試行を古い順に表示します。待機（待ち時間）、キュー（期限到来、未取得）、実行（終了状態で色分け）、待機中（シグナルまたはバッチ待ち）で、一時停止は別の行に表示します。下の試行テーブルにも同じ時間が載っています。破線は待機が期限を過ぎた時点を示します。
         empty: 試行はまだありません。
         paused_period_html: "%{from} から %{duration} 一時停止"
         paused_row: 一時停止
@@ -1465,3 +1467,4 @@ ja:
           waited: 待機済み
           waiting: 待機中
         title: タイムライン
+        wait_timeout_html: "%{step} の待機が %{time} に期限を過ぎました（on_timeout: %{action}）。"

data/config/locales/nb.yml

@@ -1349,6 +1349,8 @@ nb:
         unknown_html: 'Status: %{status}.'
         waiting_batch_html: Venter på gruppen %{batch} (%{done} av %{total} jobber ferdige).
         waiting_signal_html: Venter på signalet %{signal} siden %{ago}.
+        waiting_signal_late_html: Venter på signalet %{signal} siden %{ago} (forsinket siden %{late}). Neste forsinkelsesvarsel sendes %{time}.
+        waiting_signal_notify_html: Venter på signalet %{signal} siden %{ago}. Et forsinkelsesvarsel sendes %{time}, og ventingen fortsetter.
         waiting_signal_timeout_html: Venter på signalet %{signal} siden %{ago}. Ventetiden utløper %{time}.
         waiting_step_html: Venter på %{step}.
       not_found:
@@ -1451,7 +1453,7 @@ nb:
         ready: Klare
         waiting: Venter
       timeline:
-        caption: 'Hvert forsøk, eldst øverst: ventet (ventetiden), i kø (forfalt, ikke hentet ennå), kjørte (farget etter utfall) og venter (på et signal eller sin gruppe), med pausene på en egen rad. Forsøkstabellen under viser de samme varighetene.'
+        caption: 'Hvert forsøk, eldst øverst: ventet (ventetiden), i kø (forfalt, ikke hentet ennå), kjørte (farget etter utfall) og venter (på et signal eller sin gruppe), med pausene på en egen rad. Forsøkstabellen under viser de samme varighetene. En stiplet linje markerer hver gang en ventetid passerte fristen.'
         empty: Ingen forsøk ennå.
         paused_period_html: Satt på pause %{from} i %{duration}
         paused_row: På pause
@@ -1465,3 +1467,4 @@ nb:
           waited: Ventet
           waiting: Venter
         title: Tidslinje
+        wait_timeout_html: 'Ventetiden for %{step} passerte fristen %{time} (on_timeout: %{action}).'

data/config/locales/nl.yml

@@ -1349,6 +1349,8 @@ nl:
         unknown_html: 'Status: %{status}.'
         waiting_batch_html: Wacht op groep %{batch} (%{done} van %{total} taken klaar).
         waiting_signal_html: Wacht op signaal %{signal}, gestart %{ago}.
+        waiting_signal_late_html: Wacht op signaal %{signal}, gestart %{ago} (te laat sinds %{late}). De volgende melding over de vertraging gaat %{time} uit.
+        waiting_signal_notify_html: Wacht op signaal %{signal}, gestart %{ago}. Een melding over de vertraging gaat %{time} uit, en het wachten gaat door.
         waiting_signal_timeout_html: Wacht op signaal %{signal}, gestart %{ago}. De wachttijd verloopt %{time}.
         waiting_step_html: Wacht op %{step}.
       not_found:
@@ -1451,7 +1453,7 @@ nl:
         ready: Klaar
         waiting: Wachtend
       timeline:
-        caption: 'Elke poging, oudste bovenaan: gewacht (de wachttijd), in wachtrij (aan de beurt, nog niet opgepakt), uitgevoerd (gekleurd naar hoe het afliep) en wachtend (op een signaal of de groep), met de pauzes op een eigen rij. De pogingentabel hieronder toont dezelfde duren.'
+        caption: 'Elke poging, oudste bovenaan: gewacht (de wachttijd), in wachtrij (aan de beurt, nog niet opgepakt), uitgevoerd (gekleurd naar hoe het afliep) en wachtend (op een signaal of de groep), met de pauzes op een eigen rij. De pogingentabel hieronder toont dezelfde duren. Een stippellijn markeert elke keer dat een wachttijd zijn deadline passeerde.'
         empty: Nog geen pogingen.
         paused_period_html: Gepauzeerd op %{from} gedurende %{duration}
         paused_row: Gepauzeerd
@@ -1465,3 +1467,4 @@ nl:
           waited: Gewacht
           waiting: Wachtend
         title: Tijdlijn
+        wait_timeout_html: 'De wachttijd van %{step} verstreek op %{time} (on_timeout: %{action}).'

data/config/locales/pt.yml

@@ -1349,6 +1349,8 @@ pt:
         unknown_html: 'Status: %{status}.'
         waiting_batch_html: Aguardando o lote %{batch} (%{done} de %{total} trabalhos concluídos).
         waiting_signal_html: Aguardando o sinal %{signal} desde %{ago}.
+        waiting_signal_late_html: Aguardando o sinal %{signal} desde %{ago} (atrasado desde %{late}). O próximo aviso de atraso sai %{time}.
+        waiting_signal_notify_html: Aguardando o sinal %{signal} desde %{ago}. Um aviso de atraso sai %{time} e a espera continua.
         waiting_signal_timeout_html: Aguardando o sinal %{signal} desde %{ago}. A espera expira %{time}.
         waiting_step_html: Aguardando %{step}.
       not_found:
@@ -1451,7 +1453,7 @@ pt:
         ready: Prontos
         waiting: Aguardando
       timeline:
-        caption: 'Cada tentativa, a mais antiga no topo: esperou (sua espera), na fila (vencida, ainda não pega), executou (colorida conforme terminou) e aguardando (um sinal ou seu lote), com as pausas em linha própria. A tabela de tentativas abaixo lista as mesmas durações.'
+        caption: 'Cada tentativa, a mais antiga no topo: esperou (sua espera), na fila (vencida, ainda não pega), executou (colorida conforme terminou) e aguardando (um sinal ou seu lote), com as pausas em linha própria. A tabela de tentativas abaixo lista as mesmas durações. Uma linha tracejada marca cada vez que uma espera passou do prazo.'
         empty: Ainda não há tentativas.
         paused_period_html: Em pausa desde %{from} durante %{duration}
         paused_row: Em pausa
@@ -1465,3 +1467,4 @@ pt:
           waited: Esperou
           waiting: Aguardando
         title: Linha do tempo
+        wait_timeout_html: 'A espera de %{step} passou do prazo em %{time} (on_timeout: %{action}).'

data/config/locales/sv.yml

@@ -1349,6 +1349,8 @@ sv:
         unknown_html: 'Status: %{status}.'
         waiting_batch_html: Väntar på gruppen %{batch} (%{done} av %{total} jobb klara).
         waiting_signal_html: Väntar på signalen %{signal} sedan %{ago}.
+        waiting_signal_late_html: Väntar på signalen %{signal} sedan %{ago} (sen sedan %{late}). Nästa förseningsavisering går ut %{time}.
+        waiting_signal_notify_html: Väntar på signalen %{signal} sedan %{ago}. En förseningsavisering går ut %{time}, och väntan fortsätter.
         waiting_signal_timeout_html: Väntar på signalen %{signal} sedan %{ago}. Väntan tar slut %{time}.
         waiting_step_html: Väntar på %{step}.
       not_found:
@@ -1451,7 +1453,7 @@ sv:
         ready: Redo
         waiting: Väntar
       timeline:
-        caption: 'Varje försök, äldst överst: väntade (dess väntetid), köad (förfallen, ännu inte hämtad), körde (färgad efter utfall) och väntar (på en signal eller sin grupp), med pauserna på en egen rad. Försökstabellen nedan visar samma tider.'
+        caption: 'Varje försök, äldst överst: väntade (dess väntetid), köad (förfallen, ännu inte hämtad), körde (färgad efter utfall) och väntar (på en signal eller sin grupp), med pauserna på en egen rad. Försökstabellen nedan visar samma tider. En streckad linje markerar varje gång en väntan passerade sin tidsgräns.'
         empty: Inga försök ännu.
         paused_period_html: Pausad %{from} i %{duration}
         paused_row: Pausad
@@ -1465,3 +1467,4 @@ sv:
           waited: Väntade
           waiting: Väntar
         title: Tidslinje
+        wait_timeout_html: 'Väntan för %{step} passerade sin tidsgräns %{time} (on_timeout: %{action}).'

data/lib/pgbus/active_job/adapter.rb

@@ -80,6 +80,7 @@ module Pgbus
         # reset: once the send returns, msg_id is set and the rescue routes
         # on that instead.
         sending = false
+        retry_lock = hand_lock_to_retry(active_job, payload_hash, queue)
 
         if key && concurrency
           # The check and the park commit together, under the semaphore row
@@ -115,6 +116,9 @@ module Pgbus
         # Bind before backfill so a live message is never left with an unbound
         # uniqueness row if execution-row bookkeeping raises.
         bind_acquired_uniqueness_lock(queue, msg_id) if msg_id
+        bind_retry_lock(retry_lock, queue, msg_id) if msg_id
+        # Dropped by its concurrency limit: no retry will run, the attempt does.
+        return_retry_lock(retry_lock) unless msg_id || blocked
         Batch.backfill_execution(payload_hash, msg_id, physical_queue(queue, priority)) if msg_id
         # A retry re-enqueue that is now live (sent, or parked as a blocked
         # execution) must stop the original attempt from signalling completion.
@@ -135,6 +139,7 @@ module Pgbus
         # database error from the slot upsert or the park is not ambiguous.
         if msg_id.nil? && !(sending && ambiguous_delivery?(e))
           rollback_acquired_uniqueness_lock
+          return_retry_lock(retry_lock)
           uncount_batch_job(payload_hash, active_job)
         else
           # Drop the thread-local so a later discard on this thread cannot
@@ -247,9 +252,10 @@ module Pgbus
         # the executor still holds the key (it releases only on success/DLQ). So
         # a re-enqueue with executions > 0 would otherwise hit its own held key,
         # be rejected as a duplicate (JobNotUnique), and dead-letter the original
-        # while losing the retry. Let the retry through; the existing key row
-        # correctly stays held until the job finally succeeds or dead-letters.
-        # See issue #333.
+        # while losing the retry. Let the retry through (issue #333); the key
+        # row is handed to it (hand_lock_to_retry, then bind_retry_lock once
+        # sent), so the attempt's release leaves it held until the job finally
+        # succeeds or dead-letters (issue #564).
         return false if active_job.executions.to_i.positive?
 
         result = Uniqueness.acquire_enqueue_lock(uniqueness_key, active_job, queue_name: queue)
@@ -285,6 +291,78 @@ module Pgbus
         Pgbus.logger.warn { "[Pgbus] Uniqueness bind failed: #{e.message}" }
       end
 
+      # The job's :until_executed key and the delivery of the attempt running
+      # it, when this enqueue is that attempt's retry: the retry is let
+      # through the key the attempt holds and never acquires one, so the key
+      # row has to follow it. nil for a first attempt (it acquired its own
+      # row), a retry enqueued outside the executor (no attempt to take it
+      # from), or a job run inline inside another job, whose delivery it sees.
+      def retry_uniqueness_lock(active_job, payload_hash)
+        key = Uniqueness.extract_key(payload_hash)
+        return unless key && Uniqueness.extract_strategy(payload_hash) == :until_executed
+        return unless active_job.executions.to_i.positive?
+
+        delivery = Delivery.current
+        [key, delivery] if delivery && delivery[:job_id] == active_job.job_id
+      end
+
+      # Take the attempt's row for its retry before the retry exists — sent or
+      # parked — the way a first enqueue acquires before its send (see
+      # UniquenessKey.unbind!). Returns [key, delivery, stamp] for
+      # bind_retry_lock / return_retry_lock, or nil when there is nothing to
+      # hand over. A failure is logged and the retry goes out without the row,
+      # which then stays with the attempt.
+      def hand_lock_to_retry(active_job, payload_hash, queue)
+        key, delivery = retry_uniqueness_lock(active_job, payload_hash)
+        return unless key
+
+        stamp = UniquenessKey.unbind!(key, from_queue_name: Uniqueness.lock_queue_name(delivery[:queue_name]),
+                                           from_msg_id: delivery[:msg_id], from_enqueued_at: delivery[:enqueued_at],
+                                           queue_name: Uniqueness.lock_queue_name(queue))
+        return [key, delivery, stamp] if stamp
+
+        warn_retry_lock_not_held(key)
+        nil
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness handoff to retry failed for #{key}: #{e.message}" }
+        nil
+      end
+
+      # Point the handed-over row at the sent retry. The retry is live, so a
+      # failure is logged, not raised: the row stays unbound and stamped
+      # before the send, and the retry's own release takes it.
+      def bind_retry_lock(retry_lock, queue, msg_id)
+        return unless retry_lock
+
+        key, _delivery, stamp = retry_lock
+        UniquenessKey.bind!(key, queue_name: Uniqueness.lock_queue_name(queue), msg_id: msg_id, acquired_at: stamp)
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness bind to retry failed for #{key}: #{e.message}" }
+      end
+
+      # No retry came of it (dropped by its concurrency limit, or the send
+      # failed before any message existed): bind the row back to the attempt,
+      # which runs on and releases it when it finishes.
+      def return_retry_lock(retry_lock)
+        return unless retry_lock
+
+        key, delivery, stamp = retry_lock
+        UniquenessKey.bind!(key, queue_name: Uniqueness.lock_queue_name(delivery[:queue_name]),
+                                 msg_id: delivery[:msg_id], acquired_at: stamp)
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus] Uniqueness return to the attempt failed for #{key}: #{e.message}" }
+      end
+
+      # The row is gone (released by an operator, reaped) or a successor's:
+      # the retry runs without the key, and a fresh enqueue is not deduped
+      # against it.
+      def warn_retry_lock_not_held(key)
+        Pgbus.logger.warn do
+          "[Pgbus] Uniqueness key #{key} is no longer held by the attempt that enqueued its retry; " \
+            "the retry runs without it"
+        end
+      end
+
       # Reverses inject_batch_metadata for a job discarded at enqueue time
       # (uniqueness duplicate or concurrency :discard conflict): the message is
       # never sent, so it can never signal completion. Only applies to a job

data/lib/pgbus/active_job/delivery.rb

@@ -4,23 +4,30 @@ module Pgbus
   module ActiveJob
     # The PGMQ delivery of the job running in this fiber:
     #
-    #   Pgbus::ActiveJob::Delivery.current # => { msg_id: 42, read_ct: 2, queue_name: "default" }
+    #   Pgbus::ActiveJob::Delivery.current
+    #   # => { msg_id: 42, read_ct: 2, queue_name: "default",
+    #   #      enqueued_at: "2026-10-18 10:30:00+00", job_id: "8f0c…" }
     #
     # Set by Executor#execute around perform_now and cleared after, also when
     # the job raises; nil outside the executor (perform_now in a test, a
     # top-level inline-adapter job). A job run inline from inside an executing
     # job sees the enclosing job's delivery; StepJob only acts on it when the
-    # step row's msg_id matches, so that is harmless. Fiber-local (Thread.current[]), so concurrent jobs under
+    # step row's msg_id matches, and the adapter only when job_id is its own,
+    # so that is harmless. Fiber-local (Thread.current[]), so concurrent jobs under
     # execution_mode: :async each see their own. Pgbus::Workflow::StepJob reads
-    # read_ct to tell a redelivery after a worker died from a first delivery.
+    # read_ct to tell a redelivery after a worker died from a first delivery;
+    # the adapter reads the message identity and enqueued_at to move the
+    # job's uniqueness lock onto a retry the job enqueues (issue #564).
     #
-    # The three values sit in three fiber-locals and the Hash is built only
+    # The values sit in one fiber-local each and the Hash is built only
     # when read: setting them allocates nothing, which keeps the executor's
     # per-job allocation budget (spec/pgbus/active_job/executor_allocation_budget_spec.rb).
     module Delivery
       MSG_ID_KEY = :pgbus_delivery_msg_id
       READ_CT_KEY = :pgbus_delivery_read_ct
       QUEUE_NAME_KEY = :pgbus_delivery_queue_name
+      ENQUEUED_AT_KEY = :pgbus_delivery_enqueued_at
+      JOB_ID_KEY = :pgbus_delivery_job_id
 
       module_function
 
@@ -28,21 +35,28 @@ module Pgbus
         msg_id = Thread.current[MSG_ID_KEY]
         return nil if msg_id.nil?
 
-        { msg_id: msg_id, read_ct: Thread.current[READ_CT_KEY], queue_name: Thread.current[QUEUE_NAME_KEY] }
+        { msg_id: msg_id, read_ct: Thread.current[READ_CT_KEY], queue_name: Thread.current[QUEUE_NAME_KEY],
+          enqueued_at: Thread.current[ENQUEUED_AT_KEY], job_id: Thread.current[JOB_ID_KEY] }
       end
 
-      def with(msg_id:, read_ct:, queue_name:)
+      def with(msg_id:, read_ct:, queue_name:, enqueued_at: nil, job_id: nil)
         previous_msg_id = Thread.current[MSG_ID_KEY]
         previous_read_ct = Thread.current[READ_CT_KEY]
         previous_queue_name = Thread.current[QUEUE_NAME_KEY]
+        previous_enqueued_at = Thread.current[ENQUEUED_AT_KEY]
+        previous_job_id = Thread.current[JOB_ID_KEY]
         Thread.current[MSG_ID_KEY] = msg_id
         Thread.current[READ_CT_KEY] = read_ct
         Thread.current[QUEUE_NAME_KEY] = queue_name
+        Thread.current[ENQUEUED_AT_KEY] = enqueued_at
+        Thread.current[JOB_ID_KEY] = job_id
         yield
       ensure
         Thread.current[MSG_ID_KEY] = previous_msg_id
         Thread.current[READ_CT_KEY] = previous_read_ct
         Thread.current[QUEUE_NAME_KEY] = previous_queue_name
+        Thread.current[ENQUEUED_AT_KEY] = previous_enqueued_at
+        Thread.current[JOB_ID_KEY] = previous_job_id
       end
     end
   end

data/lib/pgbus/active_job/executor.rb

@@ -33,7 +33,7 @@ module Pgbus
           FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i)
           signal_concurrency(payload)
           signal_batch_discarded(payload)
-          Uniqueness.release_lock(Uniqueness.extract_key(payload))
+          release_uniqueness_lock(Uniqueness.extract_key(payload), queue_name, message)
           record_stat(payload, queue_name, "dead_lettered", execution_start, message: message)
           instrument(
             "pgbus.job_dead_lettered",
@@ -100,7 +100,10 @@ module Pgbus
           assign_batch_id(job, payload)
           Pgbus.logger.debug { "[Pgbus::Executor] running #{log_tag(message, queue_name)} job_class=#{job_class}" }
           with_visibility_heartbeat(job, queue_name, msg_id, source_queue, payload) do
-            Delivery.with(msg_id: msg_id, read_ct: read_count, queue_name: queue_name) { execute_job(job) }
+            Delivery.with(msg_id: msg_id, read_ct: read_count, queue_name: queue_name,
+                          enqueued_at: message.enqueued_at, job_id: payload["job_id"]) do
+              execute_job(job)
+            end
           end
           # retry_on re-enqueues from inside perform_now and returns normally:
           # this attempt is done (archive it) but the job is not — the retry
@@ -121,7 +124,7 @@ module Pgbus
           end
           Pgbus.logger.debug { "[Pgbus::Executor] archived #{log_tag(message, queue_name)} job_class=#{job_class}" }
           job_succeeded = true
-          release_uniqueness_lock(uniqueness_key)
+          release_uniqueness_lock(uniqueness_key, queue_name, message)
           # Only FailedEventRecorder.record! writes this table, and only after a
           # failed attempt, so a first delivery has no row: skip the per-job
           # DELETE round trip (issue #484). A stale row from a dropped-and-
@@ -146,7 +149,7 @@ module Pgbus
         # A failed :while_executing attempt is no longer executing — release
         # so the retry (same message, after VT) can acquire. :until_executed
         # keeps its lock until success/DLQ by design (#126, #333).
-        release_uniqueness_lock(uniqueness_key) if uniqueness_strategy == :while_executing
+        release_uniqueness_lock(uniqueness_key, queue_name, message) if uniqueness_strategy == :while_executing
         instrument(
           "pgbus.job_failed",
           queue: queue_name,
@@ -192,10 +195,15 @@ module Pgbus
         job.batch_id = batch_id
       end
 
-      def release_uniqueness_lock(key)
+      # Releases only the row this message holds, never the key as such: a
+      # row the job moved onto its retry (issue #564), or a successor's, stays.
+      # The queue is spelled as the row was bound (Uniqueness.lock_queue_name),
+      # as for release_duplicate_execution_lock.
+      def release_uniqueness_lock(key, queue_name, message)
         return unless key
 
-        Uniqueness.release_lock(key)
+        UniquenessKey.release_held_by!(key, queue_name: Uniqueness.lock_queue_name(queue_name, config: config),
+                                            msg_id: message.msg_id.to_i, enqueued_at: message.enqueued_at)
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Uniqueness release failed: #{e.message}" }
       end
@@ -425,7 +433,8 @@ module Pgbus
 
         # Same queue the execution lock was acquired under, so the match
         # cannot land on another queue's message of the same id.
-        UniquenessKey.release_if_bound!(uniqueness_key, queue_name: queue_name, msg_id: msg_id)
+        UniquenessKey.release_if_bound!(uniqueness_key, queue_name: Uniqueness.lock_queue_name(queue_name, config: config),
+                                                        msg_id: msg_id)
       rescue StandardError => e
         Pgbus.logger.warn { "[Pgbus] Duplicate-execution lock release failed: #{e.message}" }
       end
@@ -442,7 +451,8 @@ module Pgbus
         end
         headers = DeadLetterHeader.build(
           existing: message.headers, reason: DeadLetterHeader::REASON_MAX_RETRIES, source: "worker",
-          source_queue: source_queue || config.queue_name(queue_name), attempts: message.read_ct.to_i,
+          source_queue: source_queue || config.queue_name(queue_name), source_msg_id: message.msg_id.to_i,
+          source_enqueued_at: message.enqueued_at, attempts: message.read_ct.to_i,
           max_retries: config.max_retries, error: last_error
         )
         if source_queue

data/lib/pgbus/concurrency/blocked_execution.rb

@@ -16,13 +16,21 @@ module Pgbus
         # once. Handing it a pre-serialized String stored a JSON *string*
         # (double-encoded), which every document reader of the column —
         # `payload->>'job_id'`, the job-class lookup, `scheduled_at` — misread.
+        #
+        # created_at is left to the column's CURRENT_TIMESTAMP default: the
+        # job's uniqueness lock is stamped by the database too, and discarding
+        # a parked job releases only a lock acquired no later than the park
+        # (UniquenessKey.release_if_unbound!), so both sides need one clock.
         def insert(concurrency_key:, queue_name:, payload:, duration:, priority: 0)
-          Pgbus::BlockedExecution.create!(
-            concurrency_key: concurrency_key,
-            queue_name: queue_name,
-            payload: payload,
-            priority: priority,
-            expires_at: Time.current + duration
+          Pgbus::BlockedExecution.insert!(
+            {
+              concurrency_key: concurrency_key,
+              queue_name: queue_name,
+              payload: payload,
+              priority: priority,
+              expires_at: Time.current + duration
+            },
+            record_timestamps: false
           )
         end
 

data/lib/pgbus/configuration.rb

@@ -13,7 +13,8 @@ module Pgbus
     attr_accessor :database_url, :connection_params, :pool_size, :pool_timeout
 
     # Queue settings
-    attr_accessor :default_queue, :queue_prefix
+    attr_accessor :default_queue
+    attr_reader :queue_prefix # rubocop:disable Style/AccessorGrouping -- the writer normalizes (see queue_prefix=)
 
     # Worker settings
     attr_accessor :polling_interval, :prefetch_limit, :execution_mode
@@ -597,6 +598,25 @@ module Pgbus
       @finalized = false
     end
 
+    # Stored the way the queue tables spell it ("my-app" → "my_app"). Table
+    # names are unchanged (queue_name normalizes the joined name the same
+    # way), but code that strips the prefix off a table name to get its queue
+    # back (the dashboard, the worker, a job's uniqueness lock queue) then
+    # finds it. A value normalize cannot spell (nothing table-safe left, or
+    # too long) is kept as given, as before: validate! rejects one that is
+    # too long, and queue_name drops one with nothing table-safe in it.
+    def queue_prefix=(value)
+      @queue_prefix = if value.is_a?(String) && !value.empty?
+                        begin
+                          QueueNameValidator.normalize(value)
+                        rescue ArgumentError
+                          value
+                        end
+                      else
+                        value
+                      end
+    end
+
     def queue_name(name)
       full = "#{queue_prefix}_#{name}"
       QueueNameValidator.normalize(full)
@@ -1002,6 +1022,27 @@ module Pgbus
       raise Pgbus::ConfigurationError, "capsule processes must be a positive Integer (got #{value.inspect})"
     end
 
+    # A prefix with a leading, trailing or doubled underscore is kept as
+    # written (its tables already exist under it), but queue_name collapses
+    # the separator after it only for a queue name that needs normalizing:
+    # "myapp_" gives myapp__orders yet myapp_orders_handler for
+    # "orders-handler". A job's own release and the dashboard derive the same
+    # lock queue for it and still match, but the reaper cannot resolve that
+    # name back to the table, so a lock orphaned there is never reclaimed and
+    # has to be released by key. Legal, but warned.
+    def warn_queue_prefix_underscores
+      return unless queue_prefix.match?(/\A_|_\z|__/)
+
+      suggested = queue_prefix.squeeze("_").delete_prefix("_").delete_suffix("_")
+      suggestion = suggested.empty? ? "" : "; prefer #{suggested.inspect} for new deployments"
+      Pgbus.logger.warn do
+        "[Pgbus] queue_prefix #{queue_prefix.inspect} has a leading, trailing or doubled underscore — a queue " \
+          "whose name needs normalizing (\"orders-handler\") gets a table spelled unlike its queue, so the " \
+          "reaper cannot find that table: a uniqueness lock orphaned there (a worker crash before its release) " \
+          "is never reclaimed and has to be released by key#{suggestion}"
+      end
+    end
+
     # Buffered claims are kept invisible only by the visibility heartbeat.
     # Without it a message buffered longer than visibility_timeout can be
     # claimed by another worker while it still waits here. Legal, but warned.
@@ -1075,6 +1116,7 @@ module Pgbus
       { queue_prefix: queue_prefix, default_queue: default_queue }.each do |name, value|
         raise Pgbus::ConfigurationError, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
       end
+      warn_queue_prefix_underscores
 
       # web_auth gates the dashboard; a non-callable value silently leaves it
       # open (mirror streams_presence_member).

data/lib/pgbus/dead_letter_header.rb

@@ -30,7 +30,13 @@ module Pgbus
 
     # error: FailedEventRecorder.last_error's Hash, or nil when no failure
     # was recorded. Returns the merged headers as a JSON string.
-    def build(existing:, reason:, source:, source_queue:, attempts:, max_retries:, error: nil, now: Time.now.utc)
+    # source_msg_id / source_enqueued_at: the message's id in source_queue and
+    # when it was sent (the copy gets a new id and enqueued_at in the DLQ).
+    # A discard of the copy uses both to release only the uniqueness lock the
+    # original still holds: bound to it, or unbound and acquired before its
+    # send, never a lock it handed to a retry after (issue #564).
+    def build(existing:, reason:, source:, source_queue:, attempts:, max_retries:, error: nil, source_msg_id: nil,
+              source_enqueued_at: nil, now: Time.now.utc)
       headers = decode(existing, warn: true)
       retries = count(headers.delete(RETRIES_KEY))
       block = {
@@ -42,6 +48,8 @@ module Pgbus
         "max_retries" => max_retries,
         "dead_lettered_at" => iso(now)
       }
+      block["source_msg_id"] = source_msg_id if source_msg_id
+      block["source_enqueued_at"] = iso(source_enqueued_at) if source_enqueued_at
       block["retries_from_dlq"] = retries if retries.positive?
       block.merge!(error_fields(error)) if error
       JSON.generate(headers.merge(KEY => block))

data/lib/pgbus/instrumentation.rb

@@ -79,9 +79,10 @@ module Pgbus
   #                                  payload: workflow_class, workflow_id, name, duplicate,
   #                                  woke (true when it woke the step waiting for it)
   #   pgbus.workflow.wait_timed_out — a waiting step's wait_timeout: passed; its on_timeout
-  #                                  applied (the sweep, or TestHelpers#expire_wait)
+  #                                  applied (the sweep, or TestHelpers#expire_wait); under
+  #                                  notify the step keeps waiting, once per sweep that finds it late
   #                                  payload: workflow_class, workflow_id, step_name, attempt,
-  #                                  action (pause! | cancel! | skip! | run)
+  #                                  action (pause! | cancel! | skip! | run | notify)
   #   pgbus.workflow.gauge         — emitted by each dispatcher workflow sweep
   #                                  payload: statuses ([{ workflow_class:, status:, count: }]),
   #                                  stuck ([{ workflow_class:, reason:, count: }]), zero-filled

data/lib/pgbus/integrations/appsignal/dashboard.json

@@ -4,7 +4,7 @@
   ],
   "dashboard": {
     "title": "Pgbus",
-    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\nWorkflow step outcomes and run times, and stuck workflows.\n",
+    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\nWorkflow step outcomes and run times, stuck workflows and late waits.\n",
     "visuals": [
       {
         "type": "timeseries",
@@ -520,6 +520,35 @@
             ]
           }
         ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Late workflow waits",
+        "description": "Deadlines an on_timeout: :notify wait missed, by class and step: the run keeps waiting for its signal.",
+        "line_label": "%workflow_class% - %step%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflow_wait_overdue_total",
+            "fields": [
+              {
+                "field": "COUNTER"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "step",
+                "value": "*"
+              }
+            ]
+          }
+        ]
       }
     ]
   }

data/lib/pgbus/metrics/workflow_metrics.rb

@@ -12,6 +12,7 @@ module Pgbus
     #   pgbus_workflows_paused_total{workflow_class, error_class}            counter (error_class absent for a manual pause)
     #   pgbus_workflows_cancelled_total{workflow_class}                      counter
     #   pgbus_workflow_stalls_total{workflow_class, step, detection}         counter (detection: redelivery | sweep)
+    #   pgbus_workflow_wait_overdue_total{workflow_class, step}              counter (a late notice of an on_timeout: :notify wait)
     #   pgbus_workflows{workflow_class, status}                              gauge, from each sweep
     #   pgbus_workflows_stuck{workflow_class, reason}                        gauge, from each sweep
     #
@@ -20,7 +21,7 @@ module Pgbus
     module WorkflowMetrics
       EVENTS = %w[
         pgbus.workflow.step pgbus.workflow_finished pgbus.workflow_paused pgbus.workflow_cancelled
-        pgbus.workflow.stall_detected pgbus.workflow.gauge
+        pgbus.workflow.stall_detected pgbus.workflow.wait_timed_out pgbus.workflow.gauge
       ].freeze
 
       module_function
@@ -37,6 +38,7 @@ module Pgbus
         when "pgbus.workflow_cancelled" then [counter("pgbus_workflows_cancelled_total", workflow_class: klass)]
         when "pgbus.workflow.stall_detected"
           [counter("pgbus_workflow_stalls_total", workflow_class: klass, step: payload[:step_name], detection: payload[:detection])]
+        when "pgbus.workflow.wait_timed_out" then wait_timed_out_samples(klass, payload)
         when "pgbus.workflow.gauge" then gauge_samples(payload)
         else []
         end
@@ -49,6 +51,14 @@ module Pgbus
         samples
       end
 
+      # Only :notify keeps waiting past the deadline; every other on_timeout
+      # ends the wait and is counted by the step or run it ends.
+      def wait_timed_out_samples(klass, payload)
+        return [] unless payload[:action] == "notify"
+
+        [counter("pgbus_workflow_wait_overdue_total", workflow_class: klass, step: payload[:step_name])]
+      end
+
       def gauge_samples(payload)
         statuses = Array(payload[:statuses]).map do |row|
           [:gauge, "pgbus_workflows", row[:count], { workflow_class: row[:workflow_class], status: row[:status] }]

data/lib/pgbus/process/consumer.rb

@@ -296,7 +296,8 @@ module Pgbus
         last_error = FailedEventRecorder.last_error(queue_name: queue_name, msg_id: message.msg_id.to_i)
         headers = DeadLetterHeader.build(
           existing: message.headers, reason: DeadLetterHeader::REASON_MAX_RETRIES, source: "consumer",
-          source_queue: config.queue_name(queue_name), attempts: message.read_ct.to_i,
+          source_queue: config.queue_name(queue_name), source_msg_id: message.msg_id.to_i,
+          source_enqueued_at: message.enqueued_at, attempts: message.read_ct.to_i,
           max_retries: config.max_retries, error: last_error
         )
         Pgbus.client.move_to_dead_letter(queue_name, message, headers: headers)