pgbus 0.17.0 → 0.17.2

data/lib/generators/pgbus/templates/initializer.rb.erb

@@ -36,6 +36,10 @@ Pgbus.configure do |c|
   c.workers = []
   c.capsule :default,  queues: %w[critical default], threads: 5
   c.capsule :low,      queues: %w[low],              threads: 2
+  # CPU-bound jobs (rendering, reports, PDFs): threads share one GVL, so use
+  # processes instead. Capsule-level recycle limits override the global ones.
+  # c.capsule :render,   queues: %w[render], threads: 1, processes: 4,
+  #                      max_memory_mb: 1_536
 
   # --- Worker recycling (prevents memory bloat) --------------------------
   c.max_jobs_per_worker = 10_000

data/lib/pgbus/active_job/executor.rb

@@ -19,15 +19,17 @@ module Pgbus
 
       def execute(message, queue_name, source_queue: nil)
         execution_start = monotonic_now
-        tag = "msg_id=#{message.msg_id} queue=#{queue_name} read_ct=#{message.read_ct}"
-        Pgbus.logger.debug { "[Pgbus::Executor] start #{tag}" }
+        Pgbus.logger.debug { "[Pgbus::Executor] start #{log_tag(message, queue_name)}" }
 
         payload = JSON.parse(message.message)
         job_class = payload["job_class"]
         read_count = message.read_ct.to_i
 
         if read_count > config.max_retries
-          handle_dead_letter(message, queue_name, payload, source_queue: source_queue)
+          # Read the last error before clear! deletes the only row that has
+          # it: the DLQ copy carries it in its headers (issue #495).
+          last_error = FailedEventRecorder.last_error(queue_name: queue_name, msg_id: message.msg_id.to_i)
+          handle_dead_letter(message, queue_name, payload, source_queue: source_queue, last_error: last_error)
           FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i)
           signal_concurrency(payload)
           signal_batch_discarded(payload)
@@ -40,9 +42,10 @@ module Pgbus
             job_id: payload["job_id"],
             provider_job_id: payload["provider_job_id"],
             read_ct: read_count,
-            msg_id: message.msg_id.to_i
+            msg_id: message.msg_id.to_i,
+            error: last_error&.dig(:error_class)
           )
-          Pgbus.logger.debug { "[Pgbus::Executor] dead_lettered #{tag} job_class=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] dead_lettered #{log_tag(message, queue_name)} job_class=#{job_class}" }
           return :dead_lettered
         end
         uniqueness_key = Uniqueness.extract_key(payload)
@@ -70,7 +73,7 @@ module Pgbus
           end
         end
 
-        Pgbus.logger.debug { "[Pgbus::Executor] deserialized #{tag} job_class=#{job_class}" }
+        Pgbus.logger.debug { "[Pgbus::Executor] deserialized #{log_tag(message, queue_name)} job_class=#{job_class}" }
         job_succeeded = false
         retried = false
 
@@ -95,13 +98,13 @@ module Pgbus
           # job data, so hand it to the job before perform — that is what makes
           # `batch` (and `batch.enqueue` for open batches) work inside a job.
           assign_batch_id(job, payload)
-          Pgbus.logger.debug { "[Pgbus::Executor] running #{tag} job_class=#{job_class}" }
+          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) { execute_job(job) }
           # retry_on re-enqueues from inside perform_now and returns normally:
           # this attempt is done (archive it) but the job is not — the retry
           # message carries the batch tag and signals on its own outcome.
           retried = Batch.retry_reenqueued?(payload["job_id"])
-          Pgbus.logger.debug { "[Pgbus::Executor] perform_returned #{tag} job_class=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] perform_returned #{log_tag(message, queue_name)} job_class=#{job_class}" }
           # Archiving is the exact-once claim on this execution.
           # :already_archived means another worker archived the message (our
           # heartbeat lapsed and it was redelivered): that worker owns the
@@ -109,20 +112,24 @@ module Pgbus
           # concurrency slot a second time (rails/solid_queue#761).
           if archive_from(queue_name, msg_id, source_queue: source_queue) == :already_archived
             Pgbus.logger.warn do
-              "[Pgbus::Executor] already archived elsewhere, skipping signals #{tag} job_class=#{job_class}"
+              "[Pgbus::Executor] already archived elsewhere, skipping signals #{log_tag(message, queue_name)} job_class=#{job_class}"
             end
             release_duplicate_execution_lock(uniqueness_key, uniqueness_strategy, queue_name, msg_id)
             return :duplicate
           end
-          Pgbus.logger.debug { "[Pgbus::Executor] archived #{tag} job_class=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] archived #{log_tag(message, queue_name)} job_class=#{job_class}" }
           job_succeeded = true
           release_uniqueness_lock(uniqueness_key)
-          FailedEventRecorder.clear!(queue_name: queue_name, msg_id: msg_id)
+          # 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-
+          # recreated queue reusing this msg_id is the dispatcher's to sweep.
+          FailedEventRecorder.clear!(queue_name: queue_name, msg_id: msg_id) if read_count > 1
         end
 
         instrument("pgbus.job_completed", queue: queue_name, job_class: job_class)
         record_stat(payload, queue_name, "success", execution_start, message: message)
-        Pgbus.logger.debug { "[Pgbus::Executor] done #{tag} job_class=#{job_class}" }
+        Pgbus.logger.debug { "[Pgbus::Executor] done #{log_tag(message, queue_name)} job_class=#{job_class}" }
         :success
       rescue *FATAL_EXCEPTIONS
         # Process-fatal: propagate so the supervisor/OS can react.
@@ -150,7 +157,7 @@ module Pgbus
           exception_object: e
         )
         record_stat(payload, queue_name, "failed", execution_start, message: message)
-        Pgbus.logger.debug { "[Pgbus::Executor] failed #{tag} job_class=#{payload&.dig("job_class")} error=#{e.class}" }
+        Pgbus.logger.debug { "[Pgbus::Executor] failed #{log_tag(message, queue_name)} job_class=#{payload&.dig("job_class")} error=#{e.class}" }
         # Don't signal concurrency on transient failure — the job will be retried.
         # Semaphore is released only on success or dead-lettering.
         :failed
@@ -170,6 +177,12 @@ module Pgbus
 
       private
 
+      # Built inside the logger blocks so a job pays for the string only when
+      # debug logging is on (issue #484).
+      def log_tag(message, queue_name)
+        "msg_id=#{message.msg_id} queue=#{queue_name} read_ct=#{message.read_ct}"
+      end
+
       def assign_batch_id(job, payload)
         batch_id = payload[Batch::METADATA_KEY]
         return unless batch_id && job.respond_to?(:batch_id=)
@@ -419,20 +432,26 @@ module Pgbus
         defined?(PGMQ::Errors::ConnectionError) && error.is_a?(PGMQ::Errors::ConnectionError)
       end
 
-      def handle_dead_letter(message, queue_name, payload, source_queue: nil)
+      def handle_dead_letter(message, queue_name, payload, source_queue: nil, last_error: nil)
         Pgbus.logger.warn do
           job_class = payload["job_class"] || "unknown"
-          "[Pgbus] Moving job #{job_class} to dead letter queue after #{message.read_ct} attempts"
+          error = last_error ? " (last error: #{last_error[:error_class]})" : ""
+          "[Pgbus] Moving job #{job_class} to dead letter queue after #{message.read_ct} attempts#{error}"
         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,
+          max_retries: config.max_retries, error: last_error
+        )
         if source_queue
           client.ensure_dead_letter_queue(queue_name)
           dlq_name = config.dead_letter_queue_name(queue_name)
           client.transaction do |txn|
-            txn.produce(dlq_name, message.message, headers: message.headers)
+            txn.produce(dlq_name, message.message, headers: headers)
             txn.delete(source_queue, message.msg_id.to_i)
           end
         else
-          client.move_to_dead_letter(queue_name, message)
+          client.move_to_dead_letter(queue_name, message, headers: headers)
         end
       end
     end

data/lib/pgbus/cli/dlq.rb

@@ -12,7 +12,8 @@ module Pgbus
     module DLQ
       module_function
 
-      ROW_FORMAT = "%-10s %-32s %-28s %-8s %s"
+      ROW_FORMAT = "%-10s %-32s %-28s %-8s %-26s %s"
+      REASON_WIDTH = 40
 
       def start(args, data_source: Pgbus::Web::DataSource.new)
         subcommand = args.first
@@ -41,7 +42,7 @@ module Pgbus
         end
 
         print_list_table(messages)
-        puts "-" * 96
+        puts "-" * 140
         puts "Total dead-letter messages: #{data_source.dlq_total_count} " \
              "(page #{options[:page]}, #{options[:per_page]} per page)"
       end
@@ -56,6 +57,7 @@ module Pgbus
         puts "origin:      #{origin_queue(detail[:queue_name])}"
         puts "read_ct:     #{detail[:read_ct]}"
         puts "enqueued_at: #{detail[:enqueued_at]}"
+        print_dead_letter(Pgbus::Web::DeadLetterReason.present(detail))
         puts "payload:"
         puts Pgbus::Web::PayloadFilter.filter_json(detail[:message])
       end
@@ -120,14 +122,39 @@ module Pgbus
       end
 
       def print_list_table(messages)
-        puts format(ROW_FORMAT, "MSG_ID", "DLQ QUEUE", "ORIGIN QUEUE", "READ_CT", "ENQUEUED_AT")
-        puts "-" * 96
+        puts format(ROW_FORMAT, "MSG_ID", "DLQ QUEUE", "ORIGIN QUEUE", "READ_CT", "ENQUEUED_AT", "REASON")
+        puts "-" * 140
         messages.each do |m|
+          reason = Pgbus::Web::DeadLetterReason.present(m)
           puts format(ROW_FORMAT, m[:msg_id], m[:queue_name], origin_queue(m[:queue_name]),
-                      m[:read_ct], m[:enqueued_at])
+                      m[:read_ct], m[:enqueued_at], (reason.error_class || reason.reason_key).to_s[0, REASON_WIDTH])
         end
       end
 
+      # Why the message died, from its pgbus_dead_letter header (issue #495).
+      def print_dead_letter(result)
+        if result.legacy?
+          puts "reason:      not recorded (dead-lettered before pgbus #{Pgbus::DeadLetterHeader::SINCE})"
+          return
+        end
+
+        puts "died:        #{result.died_at}"
+        puts "attempts:    #{result.attempts}/#{result.max_retries}"
+        puts "source:      #{result.source_queue}"
+        puts "reason:      #{result.reason}"
+        puts "error:       #{dead_letter_error(result)}"
+        puts "retried:     #{result.retried_before} time(s) from the DLQ before" if result.retried_before
+      end
+
+      def dead_letter_error(result)
+        return "none recorded" unless result.error_class
+
+        error = "#{result.error_class}: #{result.error_message} (attempt #{result.error_attempt})"
+        # A stored message is untrusted: newlines would break the layout and
+        # ANSI sequences could rewrite the operator's terminal.
+        error.gsub(/[\x00-\x1f\x7f]/) { |char| format("\\x%02X", char.ord) }
+      end
+
       def origin_queue(dlq_queue_name)
         dlq_queue_name.delete_suffix(Pgbus::DEAD_LETTER_SUFFIX)
       end

data/lib/pgbus/client.rb

@@ -592,7 +592,9 @@ module Pgbus
       end
     end
 
-    def move_to_dead_letter(queue_name, message)
+    # headers: what the DLQ copy carries. Movers pass the message's headers
+    # merged with a DeadLetterHeader block; the default copies them verbatim.
+    def move_to_dead_letter(queue_name, message, headers: message.headers)
       dlq_name = config.dead_letter_queue_name(queue_name)
       full_queue = config.queue_name(queue_name)
 
@@ -600,7 +602,7 @@ module Pgbus
         ensure_dead_letter_queue(queue_name)
         synchronized do
           @pgmq.transaction do |txn|
-            txn.produce(dlq_name, message.message, headers: message.headers)
+            txn.produce(dlq_name, message.message, headers: headers)
             txn.delete(full_queue, message.msg_id.to_i)
           end
         end
@@ -699,6 +701,9 @@ module Pgbus
         synchronized { @pgmq.drop_queue(name) }
       end
       @queues_created.delete(name)
+      # Failed-event rows are keyed by the name the executor saw (physical or
+      # logical); a recreated queue reuses msg_ids, so neither may survive.
+      FailedEventRecorder.clear_queue!([name, name.delete_prefix("#{config.queue_prefix}_")].uniq)
       result
     end
 

data/lib/pgbus/configuration.rb

@@ -12,6 +12,12 @@ module Pgbus
 
     # Worker settings
     attr_accessor :polling_interval, :prefetch_limit, :execution_mode
+    # read_ahead (issue #486): how many messages a worker or event consumer
+    # claims beyond its free threads and holds, heartbeated, until a thread
+    # frees. Under database latency one read then feeds many jobs instead of
+    # one. 0 (default) is off. Overridable per capsule / event_consumers entry
+    # (`read_ahead:`); prefetch_limit still caps everything claimed.
+    attr_reader :read_ahead
     # visibility_heartbeat / visibility_heartbeat_interval: while a job runs,
     # its message's visibility timeout is re-armed every interval seconds
     # (default: a third of visibility_timeout), so a job that outlives the
@@ -277,6 +283,7 @@ module Pgbus
       @visibility_heartbeat_interval = nil
 
       @prefetch_limit = nil
+      @read_ahead = 0
       @execution_mode = :threads
 
       @max_jobs_per_worker = nil
@@ -573,6 +580,31 @@ module Pgbus
       (0...priority_levels).map { |p| priority_queue_name(name, p) }
     end
 
+    def read_ahead=(value)
+      @read_ahead = value.nil? ? 0 : value
+    end
+
+    # Read-ahead for one capsule or event_consumers entry, falling back to
+    # the global read_ahead (mirrors execution_mode_for).
+    def read_ahead_for(entry)
+      entry.fetch(:read_ahead, nil) || read_ahead
+    end
+
+    # Recycle limits a capsule may set for its own workers (issue #503).
+    RECYCLE_LIMIT_KEYS = %i[max_jobs_per_worker max_memory_mb max_worker_lifetime].freeze
+
+    # How many identical worker processes the supervisor forks for one
+    # capsule (issue #503). Default 1.
+    def processes_for(entry)
+      entry.fetch(:processes, nil) || 1
+    end
+
+    # One recycle limit for a capsule, falling back to the global value
+    # (mirrors read_ahead_for). nil means the limit is off.
+    def recycle_limit_for(entry, key)
+      entry.fetch(key, nil) || public_send(key)
+    end
+
     # Returns the execution mode for a specific worker config hash,
     # falling back to the global execution_mode setting.
     def execution_mode_for(worker_config)
@@ -828,6 +860,9 @@ module Pgbus
               "prefetch_limit must be > 0"
       end
 
+      validate_read_ahead!
+      validate_capsule_processes!
+
       if priority_levels && !(priority_levels.is_a?(Integer) && priority_levels >= 1 && priority_levels <= 10)
         raise Pgbus::ConfigurationError, "priority_levels must be an integer between 1 and 10"
       end
@@ -846,6 +881,54 @@ module Pgbus
       self
     end
 
+    # Global, per-capsule and per-consumer read_ahead: a non-negative Integer.
+    def validate_read_ahead!
+      settings = [["read_ahead", read_ahead]]
+      Array(workers).each { |w| settings << ["worker read_ahead", w[:read_ahead]] unless w[:read_ahead].nil? }
+      Array(event_consumers).each { |c| settings << ["event consumer read_ahead", c[:read_ahead]] unless c[:read_ahead].nil? }
+
+      settings.each do |name, value|
+        next if value.is_a?(Integer) && !value.negative?
+
+        raise Pgbus::ConfigurationError, "#{name} must be a non-negative Integer (got #{value.inspect})"
+      end
+      warn_read_ahead_without_heartbeat(settings)
+    end
+
+    # Per-capsule processes (a positive Integer) and recycle limits (a positive
+    # number; unset falls back to the global value). The Array form of
+    # +workers=+ bypasses +capsule+, so both are checked here (issue #503).
+    def validate_capsule_processes!
+      Array(workers).each do |w|
+        validate_processes!(w[:processes]) unless w[:processes].nil?
+        RECYCLE_LIMIT_KEYS.each do |key|
+          value = w[key]
+          next if value.nil? || (value.is_a?(Numeric) && value.positive?)
+
+          raise Pgbus::ConfigurationError, "capsule #{key} must be a positive number (got #{value.inspect})"
+        end
+      end
+    end
+
+    def validate_processes!(value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise Pgbus::ConfigurationError, "capsule processes must be a positive Integer (got #{value.inspect})"
+    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.
+    def warn_read_ahead_without_heartbeat(settings)
+      return if visibility_heartbeat
+      return unless settings.any? { |_name, value| value.positive? }
+
+      Pgbus.logger.warn do
+        "[Pgbus] read_ahead is on but visibility_heartbeat is false — a message buffered longer than " \
+          "visibility_timeout (#{visibility_timeout}s) can be claimed and run by another worker"
+      end
+    end
+
     # An explicit shutdown_timeout must be a positive number; nil keeps the
     # derived drain_timeout + margin default. A value below drain_timeout is
     # legal but self-defeating (the supervisor SIGKILLs workers mid-drain), so
@@ -1163,15 +1246,23 @@ module Pgbus
     #
     #   c.capsule :critical, queues: %w[critical], threads: 5
     #   c.capsule :gated, queues: %w[gated], threads: 1, single_active_consumer: true
+    #   c.capsule :render, queues: %w[render], threads: 1, processes: 4,
+    #             max_memory_mb: 1_536, max_worker_lifetime: 6.hours
+    #
+    # processes: N forks N identical workers for the capsule (CPU-bound jobs:
+    # threads share one GVL, processes do not). The capsule-level recycle
+    # limits override the global ones for this capsule's workers only.
     #
     # Names must be unique. Queues must not overlap with capsules already
     # defined (would cause double-processing). Composes with the string DSL —
     # +c.workers "..."+ followed by +c.capsule :name, ...+ appends the
     # named capsule to the list parsed from the string.
-    def capsule(name, queues:, threads:, **)
+    def capsule(name, queues:, threads:, **options)
       raise Pgbus::ConfigurationError, "capsule queues must be a non-empty Array" unless queues.is_a?(Array) && queues.any?
       raise Pgbus::ConfigurationError, "capsule threads must be a positive Integer" unless threads.is_a?(Integer) && threads.positive?
 
+      validate_processes!(options[:processes]) unless options[:processes].nil?
+
       normalized_name = name.to_s
       @workers ||= []
 
@@ -1181,7 +1272,7 @@ module Pgbus
 
       validate_no_queue_overlap!(queues)
 
-      @workers << { name: normalized_name, queues: queues, threads: threads, ** }
+      @workers << { name: normalized_name, queues: queues, threads: threads, **options }
     end
 
     # Look up a capsule by its name. Accepts symbol or string. Returns the

data/lib/pgbus/dead_letter_header.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Pgbus
+  # The `pgbus_dead_letter` block a mover writes into a message's PGMQ
+  # headers when it moves the message to a dead-letter queue (issue #495):
+  # why it was moved, from where, after how many attempts, and the last
+  # recorded error. Pure — no I/O — so the executor, the consumer, the
+  # dashboard, MCP and the CLI all read and write the same shape.
+  #
+  # PGMQ headers travel as raw JSON strings, so every entry point accepts a
+  # String (or a Hash, or nil) and build/strip_for_retry return a String.
+  module DeadLetterHeader
+    KEY = "pgbus_dead_letter"
+    # Top-level counter on a live message retried out of a DLQ. Folded into
+    # the block as `retries_from_dlq` when the message dies again.
+    RETRIES_KEY = "pgbus_dlq_retries"
+    ORIGINAL_KEY = "pgbus_original_headers"
+    VERSION = 1
+    REASON_MAX_RETRIES = "max_retries_exceeded"
+    # The release that started writing the block: rows without it predate it.
+    SINCE = "0.18.0"
+    MESSAGE_LIMIT = 1_000
+    BACKTRACE_LINES = 10
+    BACKTRACE_LIMIT = 2_000
+
+    module_function
+
+    # 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)
+      headers = decode(existing, warn: true)
+      retries = count(headers.delete(RETRIES_KEY))
+      block = {
+        "version" => VERSION,
+        "reason" => reason,
+        "source" => source,
+        "source_queue" => source_queue,
+        "attempts" => attempts,
+        "max_retries" => max_retries,
+        "dead_lettered_at" => iso(now)
+      }
+      block["retries_from_dlq"] = retries if retries.positive?
+      block.merge!(error_fields(error)) if error
+      JSON.generate(headers.merge(KEY => block))
+    end
+
+    # The block as a string-keyed Hash, or nil. Never raises.
+    def parse(headers)
+      block = decode(headers, warn: false)[KEY]
+      block.is_a?(Hash) ? block : nil
+    end
+
+    # A live message must not claim to be dead: drop the block, and carry
+    # how many times it has come back out of a DLQ. A DLQ message has no
+    # top-level counter (build folded it into the block), so the block is
+    # the only place to read the previous count from.
+    def strip_for_retry(headers)
+      retries = count(parse(headers)&.dig("retries_from_dlq")) + 1
+      stripped = decode(headers, warn: false)
+      stripped.delete(KEY)
+      stripped[RETRIES_KEY] = retries
+      JSON.generate(stripped)
+    end
+
+    # A counter read from headers anyone could have written: an Integer or a
+    # numeric String counts, anything else is 0. Never raises, so a bad value
+    # can't stop a dead-letter.
+    def count(value)
+      case value
+      when Integer then value
+      when String then Integer(value, 10, exception: false) || 0
+      else 0
+      end
+    end
+
+    def error_fields(error)
+      {
+        "error_class" => error[:error_class],
+        "error_message" => error[:error_message]&.to_s&.slice(0, MESSAGE_LIMIT),
+        "backtrace" => backtrace_head(error[:backtrace]),
+        "error_attempt" => error[:retry_count].to_i + 1,
+        "error_recorded_at" => error[:failed_at] && iso(error[:failed_at])
+      }.compact
+    end
+
+    def backtrace_head(backtrace)
+      return if backtrace.nil? || backtrace.empty?
+
+      lines = backtrace.is_a?(Array) ? backtrace : backtrace.to_s.split("\n")
+      lines.first(BACKTRACE_LINES).join("\n").slice(0, BACKTRACE_LIMIT)
+    end
+
+    def iso(value)
+      case value
+      when Time then value.getutc.iso8601(6)
+      when String then value
+      else value.respond_to?(:to_time) ? value.to_time.utc.iso8601(6) : value.to_s
+      end
+    end
+
+    # Always a Hash. Headers that are not a JSON object are kept, not
+    # dropped, under ORIGINAL_KEY.
+    def decode(headers, warn:)
+      case headers
+      when nil, "" then {}
+      when Hash then headers.transform_keys(&:to_s)
+      else wrap(JSON.parse(headers.to_s), headers, warn)
+      end
+    rescue JSON::ParserError
+      log_kept(headers) if warn
+      { ORIGINAL_KEY => headers }
+    end
+
+    def wrap(parsed, raw, warn)
+      return parsed if parsed.is_a?(Hash)
+
+      log_kept(raw) if warn
+      { ORIGINAL_KEY => parsed }
+    end
+
+    # The raw value is not logged: headers can carry caller secrets.
+    def log_kept(_raw)
+      Pgbus.logger.warn { "[Pgbus] Dead-letter headers were not a JSON object; kept under #{ORIGINAL_KEY}" }
+    end
+  end
+end

data/lib/pgbus/doctor.rb

@@ -5,7 +5,7 @@ require "pgbus/mcp/health_analyzer"
 
 module Pgbus
   # Preflight diagnostics for a pgbus deployment — the single command that
-  # answers "is this environment healthy enough to run?". Runs eleven checks and
+  # answers "is this environment healthy enough to run?". Runs twelve checks and
   # returns a machine-readable result plus a human report, so `pgbus doctor`
   # and `rake pgbus:doctor` can gate a deploy or CI run (exit 0 on success,
   # 1 on any failure).
@@ -32,6 +32,7 @@ module Pgbus
     # stable identity of each check (used in the report and to select subsets).
     CHECKS = {
       "Configuration" => :check_configuration,
+      "Ruby JIT" => :check_ruby_jit,
       "Database" => :check_database,
       "PGMQ schema" => :check_pgmq_schema,
       "Queues" => :check_queues,
@@ -166,6 +167,33 @@ module Pgbus
       Check.new(name: "Configuration", status: :fail, detail: "#{e.class}: #{e.message}")
     end
 
+    # 1b. Ruby JIT (issue #484). With Postgres close by, a worker is GVL-bound
+    # and YJIT is worth ~15-20% jobs/s (docs/performance.md). Rails enables it via
+    # config.yjit (load_defaults 7.2+, or 8.0+ outside local envs). Reports
+    # only — enabling a JIT is the application's decision, never pgbus's.
+    def check_ruby_jit
+      label = RubyJit.label
+      return Check.new(name: "Ruby JIT", status: :ok, detail: "#{label.upcase} enabled") unless label == "none"
+      return Check.new(name: "Ruby JIT", status: :ok, detail: "no YJIT available on this Ruby") unless RubyJit.yjit_available?
+      return Check.new(name: "Ruby JIT", status: :ok, detail: "YJIT off in a local environment (expected)") if local_env?
+
+      Check.new(name: "Ruby JIT", status: :warn,
+                detail: "YJIT is available but off — a CPU-bound worker (Postgres nearby) runs ~15% fewer jobs/s " \
+                        "without it; no measurable effect when network-bound. " \
+                        "Enable it with config.yjit = true (or load_defaults 7.2+) or RUBY_YJIT_ENABLE=1")
+    rescue StandardError => e
+      Check.new(name: "Ruby JIT", status: :warn, detail: "could not determine (#{e.class}: #{e.message})")
+    end
+
+    # A Rails app outside development/test. Without Rails the environment is
+    # unknown, so assume local and stay quiet rather than warn on a guess.
+    def local_env?
+      return true unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env
+
+      env = Rails.env
+      env.respond_to?(:local?) ? env.local? : %w[development test].include?(env.to_s)
+    end
+
     # 2. Database connectivity — SELECT 1 via Client#ping.
     def check_database
       @client.ping
@@ -374,23 +402,27 @@ module Pgbus
     # per worker/consumer fork. Streams add one per web-server process, which
     # the doctor cannot count from here, so it is reported as a clause.
     def check_connection_budget
-      capsules = @config.role_enabled?(:workers) ? Array(@config.workers).size : 0
+      worker_configs = @config.role_enabled?(:workers) ? Array(@config.workers) : []
+      capsules = worker_configs.size
+      # A processes: N capsule forks N workers, each with its own LISTEN under :fork scope.
+      worker_forks = worker_configs.sum { |w| @config.processes_for(w) }
       consumers = @config.role_enabled?(:consumers) ? Array(@config.event_consumers).size : 0
 
       count =
         if !@config.worker_notify_wakeup?
           0
         elsif @config.worker_notify_scope == :supervisor
-          (capsules + consumers).positive? ? 1 : 0
+          (worker_forks + consumers).positive? ? 1 : 0
         else
-          capsules + consumers
+          worker_forks + consumers
         end
 
       detail = format(
         "%<count>d direct LISTEN connection%<plural>s pinned (scope=%<scope>s; " \
-        "%<capsules>d capsule%<cap_plural>s + %<consumers>d consumer%<con_plural>s%<share>s)",
+        "%<capsules>d capsule%<cap_plural>s%<forks>s + %<consumers>d consumer%<con_plural>s%<share>s)",
         count: count, plural: count == 1 ? "" : "s", scope: @config.worker_notify_scope,
         capsules: capsules, cap_plural: capsules == 1 ? "" : "s",
+        forks: worker_forks == capsules ? "" : " (#{worker_forks} worker processes)",
         consumers: consumers, con_plural: consumers == 1 ? "" : "s",
         share: count == 1 && @config.worker_notify_scope == :supervisor ? " share it" : ""
       )

data/lib/pgbus/event_bus/handler.rb

@@ -15,6 +15,23 @@ module Pgbus
         def dedup_cache
           @dedup_cache ||= DedupCache.new
         end
+
+        # How long a pending claim may stay silent before its holder counts as
+        # dead. ClaimBeat refreshes a live claim from the visibility heartbeat,
+        # which lands every extension inside [interval, 1.5 * interval] of the
+        # previous one — two intervals leaves margin for a late beat without
+        # stretching the window past the visibility timeout it rides on.
+        #
+        # With the heartbeat disabled a claim is never refreshed, so the window
+        # degrades to "roughly the first two thirds of one visibility timeout
+        # after the claim" — a redelivery, which cannot arrive before the VT has
+        # lapsed, still re-runs exactly as it did before issue #470.
+        #
+        # The dashboard reads the same window to tell a claim being handled
+        # from one that went silent (issue #494).
+        def claim_ownership_window
+          Pgbus.configuration.effective_visibility_heartbeat_interval * 2
+        end
       end
 
       # Outcome of the two-phase claim. `age` is how long the losing delivery
@@ -196,18 +213,8 @@ module Pgbus
         ClaimResult.new(status: :claimed, age: age)
       end
 
-      # How long a pending claim may stay silent before its holder counts as
-      # dead. ClaimBeat refreshes a live claim from the visibility heartbeat,
-      # which lands every extension inside [interval, 1.5 * interval] of the
-      # previous one — two intervals leaves margin for a late beat without
-      # stretching the window past the visibility timeout it rides on.
-      #
-      # With the heartbeat disabled a claim is never refreshed, so the window
-      # degrades to "roughly the first two thirds of one visibility timeout
-      # after the claim" — a redelivery, which cannot arrive before the VT has
-      # lapsed, still re-runs exactly as it did before issue #470.
       def claim_ownership_window
-        Pgbus.configuration.effective_visibility_heartbeat_interval * 2
+        self.class.claim_ownership_window
       end
 
       # Register this claim with the message's beat for exactly the duration of

data/lib/pgbus/event_bus/registry.rb

@@ -125,6 +125,12 @@ module Pgbus
           subscription_pattern.start_with?(topic_filter.delete_suffix(".#"))
       end
 
+      # Whether +routing_key+ matches a subscription +pattern+ ("*" one word,
+      # "#" any). The dashboard checks a replay with it (issue #494).
+      def pattern_matches?(pattern, routing_key)
+        matches?(pattern, routing_key)
+      end
+
       private
 
       # True when running inside a rake schema/asset task, where setup_all!(safe:)