pgbus 0.17.1 → 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

@@ -26,7 +26,10 @@ module Pgbus
         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)
@@ -39,7 +42,8 @@ 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 #{log_tag(message, queue_name)} job_class=#{job_class}" }
           return :dead_lettered
@@ -428,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

data/lib/pgbus/configuration.rb

@@ -590,6 +590,21 @@ module Pgbus
       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)
@@ -846,6 +861,7 @@ module Pgbus
       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"
@@ -879,6 +895,27 @@ module Pgbus
       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.
@@ -1209,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 ||= []
 
@@ -1227,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

@@ -402,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:)

data/lib/pgbus/failed_event_recorder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "time"
+
 module Pgbus
   # Records job failures to pgbus_failed_events for dashboard visibility.
   # Uses upsert (INSERT ON CONFLICT UPDATE) keyed on (queue_name, msg_id)
@@ -47,6 +49,31 @@ module Pgbus
         false
       end
 
+      # The message's latest recorded failure, read by a mover just before it
+      # dead-letters the message and clears the row (issue #495). failed_at
+      # comes back as an ISO 8601 UTC string whatever the adapter decodes it
+      # to. A failed read returns nil: it must never stop a dead-letter.
+      def last_error(queue_name:, msg_id:)
+        row = connection.select_one(
+          "SELECT error_class, error_message, backtrace, retry_count, failed_at " \
+          "FROM pgbus_failed_events WHERE queue_name = $1 AND msg_id = $2 LIMIT 1",
+          "FailedEvent Last Error",
+          [queue_name, msg_id.to_i]
+        )
+        return unless row
+
+        {
+          error_class: row["error_class"],
+          error_message: row["error_message"],
+          backtrace: row["backtrace"],
+          retry_count: row["retry_count"].to_i,
+          failed_at: iso_utc(row["failed_at"])
+        }
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] FailedEvent last_error read failed: #{e.class}: #{e.message}" }
+        nil
+      end
+
       # Drops every row recorded under any of `queue_names`. Called when a
       # queue is dropped: PGMQ restarts msg_ids on recreate, so a surviving
       # row would aim the dashboard's retry/discard at an unrelated message.
@@ -82,6 +109,13 @@ module Pgbus
 
       private
 
+      def iso_utc(value)
+        time = value.is_a?(String) ? Time.parse(value) : value
+        time&.utc&.iso8601(6)
+      rescue ArgumentError
+        value.to_s
+      end
+
       def connection
         if defined?(BusRecord) && BusRecord.connected?
           BusRecord.connection

data/lib/pgbus/instrumentation.rb

@@ -15,7 +15,8 @@ module Pgbus
   #   pgbus.executor.execute       — full job execution (deserialize + perform + archive)
   #   pgbus.job_completed          — job archived successfully
   #   pgbus.job_failed             — job raised; carries :exception_object
-  #   pgbus.job_dead_lettered      — job exceeded max_retries and was DLQ-routed
+  #   pgbus.job_dead_lettered      — job exceeded max_retries and was DLQ-routed;
+  #                                  :error is the last recorded error class (or nil)
   #   pgbus.job_visibility_extended — heartbeat re-armed a running job's visibility timeout
   #                                  payload: queue, job_class, msg_id, vt, extensions
   #   pgbus.event_processed        — event handler succeeded

data/lib/pgbus/mcp/base_tool.rb

@@ -70,6 +70,31 @@ module Pgbus
           ::MCP::Tool::Response.new([{ type: "text", text: JSON.generate(redacted) }])
         end
 
+        # Past the count cap the total is a lower bound, so only a full page
+        # can have another one behind it. At the page ceiling the next call
+        # would clamp back to this page, so there is no "more" to fetch.
+        def more_pages?(count, page:, per_page:, shown:)
+          return false if page >= self::MAX_PAGE
+
+          count.capped? ? shown == per_page : page * per_page < count.total
+        end
+
+        DEAD_LETTER_SUMMARY_KEYS = %w[reason source source_queue attempts max_retries dead_lettered_at
+                                      retries_from_dlq error_class error_attempt error_recorded_at].freeze
+        DEAD_LETTER_ERROR_KEYS = %w[error_message backtrace].freeze
+
+        # Why a DLQ row died, from its DeadLetterHeader block (issue #495), or
+        # nil for a row dead-lettered before the block existed. The error
+        # message and backtrace can quote payload values, and the Redactor
+        # does not know those keys, so they are added only with include_error.
+        def dead_letter_summary(row, include_error:)
+          block = Pgbus::DeadLetterHeader.parse(row[:headers])
+          return unless block
+
+          keys = include_error ? DEAD_LETTER_SUMMARY_KEYS + DEAD_LETTER_ERROR_KEYS : DEAD_LETTER_SUMMARY_KEYS
+          block.slice(*keys)
+        end
+
         # Wrap an error message as an MCP error response (isError: true) so the
         # client surfaces it as a tool failure rather than a normal result.
         def error_response(message)

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

@@ -17,14 +17,33 @@ module Pgbus
           their limit — plus up to 100 key rows with value/limit, lease expiry,
           whether the lease is still fresh, parked count and oldest wait. A key
           with a stale lease and a parked backlog is a stuck pipeline: its holder
-          died before releasing the slot.
+          died before releasing the slot. The key rows are paginated (default
+          100 per page, capped at 100); the response also carries page,
+          per_page, total (number of keys, capped at 10000) and has_more.
         DESC
 
-        input_schema(properties: {}, required: [])
+        MAX_PER_PAGE = 100
+        MAX_PAGE = 1_000
 
-        def self.call(server_context: nil)
+        input_schema(
+          properties: {
+            page: { type: "integer", description: "1-based page number (default 1, max 1000).", minimum: 1 },
+            per_page: { type: "integer", description: "Rows per page (default 100, max 100).", minimum: 1 }
+          },
+          required: []
+        )
+
+        def self.call(page: 1, per_page: MAX_PER_PAGE, server_context: nil)
           data_source = data_source_from(server_context)
-          json_response(data_source.concurrency_stats)
+          per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
+          page = page.to_i.clamp(1, MAX_PAGE)
+          stats = data_source.concurrency_stats(page: page, per_page: per_page)
+          count = data_source.list_count(:concurrency_keys)
+
+          json_response(
+            stats.merge(page: page, per_page: per_page, total: count.total,
+                        has_more: more_pages?(count, page: page, per_page: per_page, shown: stats[:keys].size))
+          )
         end
       end
     end

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

@@ -12,7 +12,7 @@ module Pgbus
         title "Pgbus Dead-Letter Detail"
         description <<~DESC
           Inspect one dead-letter message: read_ct, vt, enqueued_at, source
-          queue. Pass the full physical DLQ queue name (e.g.
+          queue, and a dead_letter summary of why it died. Pass the full physical DLQ queue name (e.g.
           "pgbus_default_dlq") in +queue+ to disambiguate — msg_ids are only
           unique within a single DLQ table, so the same id can exist in more
           than one. Without +queue+ the tool scans every "_dlq" table and
@@ -48,7 +48,9 @@ module Pgbus
           return error_response("Dead-letter message #{msg_id} not found") unless detail
           return detail if detail.is_a?(::MCP::Tool::Response)
 
-          json_response({ message: detail }, server_context: server_context, include_payloads: include_payloads)
+          summary = dead_letter_summary(detail, include_error: payloads_allowed?(server_context, include_payloads))
+          json_response({ message: detail.merge(dead_letter: summary) },
+                        server_context: server_context, include_payloads: include_payloads)
         end
 
         # When the caller didn't specify a queue, scan every DLQ for the id and

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

@@ -10,9 +10,12 @@ module Pgbus
         title "Pgbus Dead-Letter Queue"
         description <<~DESC
           List messages sitting in dead-letter queues (queues whose name ends
-          in "_dlq") with read_ct, vt and enqueued_at. Paginated (default 25,
-          max 100). Message bodies and headers are redacted unless the server
-          allows payloads and include_payloads is set.
+          in "_dlq") with read_ct, vt and enqueued_at, and a dead_letter
+          summary of why each died (reason, source queue, attempts, error
+          class; null for messages dead-lettered before pgbus recorded it).
+          Paginated (default 25, max 100). Message bodies, headers and the
+          error message/backtrace are redacted unless the server allows
+          payloads and include_payloads is set.
         DESC
 
         MAX_PER_PAGE = 100
@@ -34,7 +37,10 @@ module Pgbus
           data_source = data_source_from(server_context)
           per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
           page = page.to_i.clamp(1, MAX_PAGE)
-          rows = data_source.dlq_messages(page: page, per_page: per_page)
+          include_error = payloads_allowed?(server_context, include_payloads)
+          rows = data_source.dlq_messages(page: page, per_page: per_page).map do |row|
+            row.merge(dead_letter: dead_letter_summary(row, include_error: include_error))
+          end
 
           json_response(
             { page: page, per_page: per_page, messages: rows },