pgbus 0.17.1 → 0.17.3

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/engine.rb

@@ -139,14 +139,20 @@ module Pgbus
       app.middleware.use Pgbus::Streams::WatermarkCacheMiddleware if Pgbus.configuration.streams_enabled
     end
 
-    # Make stream_source_element.js available to the host app's asset
-    # pipeline (Propshaft or Sprockets) so it can be included via
-    # `javascript_include_tag "pgbus/stream_source_element"` or pinned
-    # in importmap. When importmap-rails is loaded, auto-pin it so
-    # host apps get it without manual configuration.
+    # Make the <pgbus-stream-source> element available to the host app's
+    # asset pipeline (Propshaft or Sprockets). The importmap pin points at
+    # the minified build (rake frontend:js). Propshaft rewrites its
+    # sourceMappingURL to the digested .min.js.map; Sprockets serves the
+    # comment as written. The readable ES module source stays precompiled for
+    # apps that pin or bundle it themselves. When importmap-rails is loaded,
+    # auto-pin it so host apps get it without manual configuration.
     initializer "pgbus.streams.assets" do |app|
       if Pgbus.configuration.streams_enabled && app.config.respond_to?(:assets)
-        app.config.assets.precompile += %w[pgbus/stream_source_element.js]
+        app.config.assets.precompile += %w[
+          pgbus/stream_source_element.min.js
+          pgbus/stream_source_element.min.js.map
+          pgbus/stream_source_element.js
+        ]
       end
     end
 
@@ -156,7 +162,7 @@ module Pgbus
           next unless Rails.application.respond_to?(:importmap)
 
           Rails.application.importmap.pin(
-            "pgbus/stream_source_element", to: "pgbus/stream_source_element.js"
+            "pgbus/stream_source_element", to: "pgbus/stream_source_element.min.js"
           )
         end
       end

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/generators/migration_detector.rb

@@ -73,6 +73,7 @@ module Pgbus
         add_stream_stats: "pgbus:add_stream_stats",
         add_stream_queues: "pgbus:add_stream_queues",
         add_presence: "pgbus:add_presence",
+        add_presence_seats: "pgbus:add_presence_seats",
         add_queue_states: "pgbus:add_queue_states",
         add_outbox: "pgbus:add_outbox",
         add_recurring: "pgbus:add_recurring",
@@ -94,6 +95,7 @@ module Pgbus
         add_stream_stats: "stream stats table (opt-in real-time Insights)",
         add_stream_queues: "stream queue registry (per-stream retention, orphan sweep, wildcard-worker safety)",
         add_presence: "presence members table (Turbo Streams presence)",
+        add_presence_seats: "presence seats (one row per SSE connection, per-seat state)",
         add_queue_states: "queue states table (pause/resume)",
         add_outbox: "outbox entries table (transactional outbox)",
         add_recurring: "recurring tasks + executions tables",
@@ -182,8 +184,14 @@ module Pgbus
         table_exists?("pgbus_stream_queues") ? [] : [:add_stream_queues]
       end
 
+      # The add_presence template already carries the seat columns, so a
+      # missing table needs only that; an existing table without
+      # connection_id predates seats (issue #515).
       def presence_migrations
-        table_exists?("pgbus_presence_members") ? [] : [:add_presence]
+        return [:add_presence] unless table_exists?("pgbus_presence_members")
+        return [] if column_names("pgbus_presence_members").include?("connection_id")
+
+        [:add_presence_seats]
       end
 
       def queue_states_migrations

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 },

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

@@ -12,15 +12,33 @@ module Pgbus
         description <<~DESC
           List active job uniqueness locks with their lock_key, queue_name,
           msg_id, and age in seconds. A lock that outlives its message
-          indicates a leaked uniqueness key blocking re-enqueues. Returns the
-          100 most recent locks.
+          indicates a leaked uniqueness key blocking re-enqueues. Paginated
+          (default 100 per page, capped at 100); the response carries page,
+          per_page, total (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({ locks: data_source.job_locks })
+          per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
+          page = page.to_i.clamp(1, MAX_PAGE)
+          locks = data_source.job_locks(page: page, per_page: per_page)
+          count = data_source.list_count(:job_locks)
+
+          json_response(
+            { locks: locks, page: page, per_page: per_page, total: count.total,
+              has_more: more_pages?(count, page: page, per_page: per_page, shown: locks.size) }
+          )
         end
       end
     end

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

@@ -12,15 +12,44 @@ module Pgbus
         description <<~DESC
           List recurring (cron) tasks with their schedule, human-readable
           schedule, queue, enabled state, last_run_at and next_run_at. Use this
-          to confirm scheduled work is firing on time.
+          to confirm scheduled work is firing on time. Returns every task unless
+          page or per_page is given; then it is paginated (per_page defaults to
+          100, capped at 100). The response carries page, per_page, total
+          (capped at 10000 when paginated; the exact row count when not) and
+          has_more; per_page is null when unpaginated.
         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 once paginating, max 100).", minimum: 1 }
+          },
+          required: []
+        )
+
+        def self.call(page: nil, per_page: nil, server_context: nil)
           data_source = data_source_from(server_context)
-          json_response({ recurring_tasks: data_source.recurring_tasks })
+          return unpaged(data_source) if page.nil? && per_page.nil?
+
+          per_page = (per_page || MAX_PER_PAGE).to_i.clamp(1, MAX_PER_PAGE)
+          page = (page || 1).to_i.clamp(1, MAX_PAGE)
+          tasks = data_source.recurring_tasks(page: page, per_page: per_page)
+          count = data_source.list_count(:recurring_tasks)
+
+          json_response(
+            { recurring_tasks: tasks, page: page, per_page: per_page, total: count.total,
+              has_more: more_pages?(count, page: page, per_page: per_page, shown: tasks.size) }
+          )
+        end
+
+        def self.unpaged(data_source)
+          tasks = data_source.recurring_tasks
+          json_response({ recurring_tasks: tasks, page: 1, per_page: nil, total: tasks.size, has_more: false })
         end
+        private_class_method :unpaged
       end
     end
   end

data/lib/pgbus/outbox/poller.rb

@@ -139,7 +139,7 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Process::Heartbeat.new(
           kind: "outbox_poller",
-          metadata: { pid: ::Process.pid }
+          metadata: { pid: ::Process.pid, started_at: Time.now.to_f, supervisor_pid: ::Process.ppid }
         )
         @heartbeat.start
       end

data/lib/pgbus/process/consumer.rb

@@ -77,6 +77,8 @@ module Pgbus
         @claim_buffer = ClaimBuffer.new(config: config)
         @loop_tick_at = Concurrent::AtomicReference.new(nil)
         @started_at_monotonic = started_at_monotonic || monotonic_now
+        # Wall clock for the Processes page's uptime (issue #493).
+        @started_at = Time.current
         @wake_signal = WakeSignal.new
         @pool = ExecutionPools.build(
           mode: @execution_mode,
@@ -246,7 +248,7 @@ module Pgbus
 
         if message.read_ct.to_i > config.max_retries
           Pgbus.logger.warn { "[Pgbus] Consumer moving message #{message.msg_id} to DLQ after #{message.read_ct} reads" }
-          Pgbus.client.move_to_dead_letter(queue_name, message)
+          dead_letter(message, queue_name)
           record_stat(message, queue_name, "dead_lettered", execution_start)
           return
         end
@@ -263,6 +265,9 @@ module Pgbus
         end
 
         Pgbus.client.archive_message(queue_name, message.msg_id.to_i)
+        # A redelivery that succeeds leaves no stale failure behind. First
+        # deliveries never had one: no query on the hot path (#484's gate).
+        FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i) if message.read_ct.to_i > 1
         @circuit_breaker.record_success(queue_name)
         record_stat(message, queue_name, "success", execution_start)
       rescue StandardError => e
@@ -270,6 +275,9 @@ module Pgbus
         # Message stays in queue; VT will expire and it becomes available again.
         # read_ct tracks delivery attempts — when it exceeds max_retries,
         # the next read will route to DLQ above.
+        # A dead-letter read fails only in the move: keep the handler's error
+        # on the row for the next attempt's DLQ block instead of the move's.
+        record_failed_event(message, queue_name, e) unless message.read_ct.to_i > config.max_retries
         @circuit_breaker.record_failure(queue_name)
         record_stat(message, queue_name, "failed", execution_start)
       ensure
@@ -281,6 +289,31 @@ module Pgbus
         @jobs_processed.increment
       end
 
+      # Order: read the last error, move with the dead-letter block, then
+      # clear the failed-event row. A move that raises keeps the row, so the
+      # next attempt still carries the reason.
+      def dead_letter(message, queue_name)
+        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,
+          max_retries: config.max_retries, error: last_error
+        )
+        Pgbus.client.move_to_dead_letter(queue_name, message, headers: headers)
+        FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i)
+      end
+
+      # The executor's handle_failure, for events (issue #494): one upsert per
+      # failure, under the LOGICAL queue name, so the dashboard reads the event
+      # as retrying with its error. No ErrorReporter call: Handler#process!
+      # already instruments pgbus.event_failed, which feeds the reporters.
+      def record_failed_event(message, queue_name, error)
+        FailedEventRecorder.record!(
+          queue_name: queue_name, msg_id: message.msg_id.to_i, payload: message.message,
+          headers: message.headers, error: error, retry_count: [message.read_ct.to_i - 1, 0].max
+        )
+      end
+
       # Run every handler that owns this message, with the message's visibility
       # timeout held open for as long as they take (issue #470).
       #
@@ -582,13 +615,30 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Heartbeat.new(
           kind: "consumer",
-          metadata: { topics: topics, threads: threads, pid: ::Process.pid },
+          metadata: {
+            topics: topics, threads: threads, pid: ::Process.pid, execution_mode: @execution_mode,
+            started_at: @started_at.to_f, supervisor_pid: ::Process.ppid
+          },
           on_beat: -> { on_heartbeat },
-          loop_tick_supplier: -> { @loop_tick_at.get }
+          loop_tick_supplier: -> { @loop_tick_at.get },
+          metadata_supplier: -> { throughput_metadata }
         )
         @heartbeat.start
       end
 
+      # What the Processes page states about a consumer (issue #493), read
+      # once per beat, never per message. String keys: the value round-trips
+      # through JSON in the metadata column.
+      def throughput_metadata
+        pool = @pool.metadata
+        {
+          "jobs_processed" => @jobs_processed.value, "buffered" => @claim_buffer.size,
+          "capacity" => pool[:capacity], "busy" => pool[:busy], "memory_mb" => current_memory_mb,
+          "max_jobs" => config.max_jobs_per_worker, "max_memory_mb" => config.max_memory_mb,
+          "max_lifetime" => config.max_worker_lifetime
+        }.compact
+      end
+
       # Runs once per heartbeat interval (not per message), so it's the right
       # place to emit connection-pool observability without touching any per-job
       # hot path. Reading the pool must never crash the beat — pool_stats already

data/lib/pgbus/process/dispatcher.rb

@@ -697,7 +697,7 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Heartbeat.new(
           kind: "dispatcher",
-          metadata: { pid: ::Process.pid },
+          metadata: { pid: ::Process.pid, started_at: Time.now.to_f, supervisor_pid: ::Process.ppid },
           loop_tick_supplier: -> { @loop_tick_at.get }
         )
         @heartbeat.start

data/lib/pgbus/process/supervisor.rb

@@ -195,9 +195,11 @@ module Pgbus
           name = worker_config[:name] || worker_config["name"] || "anonymous"
           queues = worker_config[:queues] || worker_config["queues"] || [config.default_queue]
           threads = worker_config[:threads] || worker_config["threads"] || 5
+          processes = config.processes_for(worker_config)
           mode = banner_field { config.execution_mode_for(worker_config) }
           Pgbus.logger.info do
-            "[Pgbus] boot: capsule=#{name} queues=#{Array(queues).join(",")} threads=#{threads} mode=#{mode}"
+            "[Pgbus] boot: capsule=#{name} queues=#{Array(queues).join(",")} threads=#{threads} " \
+              "processes=#{processes} mode=#{mode}"
           end
         end
       end
@@ -284,12 +286,7 @@ module Pgbus
         # --dispatcher-only CLI flags). Each role is gated by
         # config.role_enabled?, which returns true unless +config.roles+ has
         # been narrowed.
-        if config.role_enabled?(:workers)
-          # slot is the child's position in the config array — it keys the
-          # crash-streak tracking so identically-configured siblings don't
-          # share (and reset) each other's restart backoff.
-          Array(config.workers).each_with_index { |worker_config, slot| fork_worker(worker_config, slot: slot) }
-        end
+        boot_workers if config.role_enabled?(:workers)
 
         fork_dispatcher if config.role_enabled?(:dispatcher)
         boot_scheduler if config.role_enabled?(:scheduler)
@@ -297,7 +294,22 @@ module Pgbus
         boot_outbox_poller if config.role_enabled?(:outbox)
       end
 
-      def fork_worker(worker_config, slot: nil)
+      # A capsule with processes: N forks N identical workers (issue #503).
+      # slot numbers every worker fork across all capsules — it keys the
+      # crash-streak tracking so identically-configured siblings (in one
+      # capsule or in several) don't share or reset each other's restart
+      # backoff. process_index is the fork's position within its capsule.
+      def boot_workers
+        slot = 0
+        Array(config.workers).each do |worker_config|
+          config.processes_for(worker_config).times do |process_index|
+            fork_worker(worker_config, slot: slot, process_index: process_index)
+            slot += 1
+          end
+        end
+      end
+
+      def fork_worker(worker_config, slot: nil, process_index: 0)
         note_intended_child
         queues = worker_config[:queues] || [config.default_queue]
         threads = worker_config[:threads] || 5
@@ -331,6 +343,8 @@ module Pgbus
             single_active_consumer: single_active, consumer_priority: priority,
             execution_mode: exec_mode, group_mode: grp_mode,
             read_ahead: config.read_ahead_for(worker_config),
+            recycle_limits: worker_config.slice(*Configuration::RECYCLE_LIMIT_KEYS),
+            capsule: worker_config[:name], process: process_label(worker_config, process_index),
             liveness_pipe: liveness_writer, wake_pipe: wake_reader
           )
           worker.run
@@ -352,7 +366,7 @@ module Pgbus
         close_pipe(wake_reader)
         register_fork_with_hub(pid, wake_writer, queues)
         @forks[pid] = {
-          type: :worker, config: worker_config, slot: slot, spawned_at: monotonic_now,
+          type: :worker, config: worker_config, slot: slot, process_index: process_index, spawned_at: monotonic_now,
           liveness_reader: liveness_reader, last_pipe_tick_at: monotonic_now, pipe_seen: false,
           wake_writer: wake_writer
         }
@@ -365,6 +379,13 @@ module Pgbus
         ErrorReporter.report(e, { action: "fork_worker", queues: queues })
       end
 
+      # "2/4" for the second of a capsule's four processes; nil for a
+      # single-process capsule, where it would only add noise.
+      def process_label(worker_config, process_index)
+        total = config.processes_for(worker_config)
+        "#{process_index + 1}/#{total}" if total > 1
+      end
+
       # Hand the hub a worker fork's routing entry: explicit queues as
       # physical names, "*" as the unconditional wildcard flag (the hub wakes
       # wildcard forks for every channel, so the fork's own resolved set never
@@ -682,7 +703,7 @@ module Pgbus
       def restart_child(info)
         case info[:type]
         when :worker
-          fork_worker(info[:config], slot: info[:slot])
+          fork_worker(info[:config], slot: info[:slot], process_index: info[:process_index] || 0)
         when :dispatcher
           fork_dispatcher
         when :scheduler
@@ -882,7 +903,7 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Heartbeat.new(
           kind: "supervisor",
-          metadata: { pid: ::Process.pid, hostname: Socket.gethostname }
+          metadata: { pid: ::Process.pid, hostname: Socket.gethostname, started_at: Time.now.to_f }
         )
         @heartbeat.start
       end