pgbus 0.17.1 → 0.17.2

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

data/lib/pgbus/process/worker.rb

@@ -35,7 +35,8 @@ module Pgbus
                      rate_counter: nil, wake_signal: nil, stat_buffer: :default,
                      notify_listener: nil, notify_retry_at: 0.0,
                      notify_retry_backoff: NOTIFY_RETRY_BASE_SECONDS,
-                     started_at_monotonic: nil, wake_pipe: nil, read_ahead: nil)
+                     started_at_monotonic: nil, wake_pipe: nil, read_ahead: nil,
+                     recycle_limits: {}, capsule: nil, process: nil)
         @queues = Array(queues)
         @initial_queues = @queues.dup.freeze
         @wildcard = @queues.include?("*")
@@ -68,6 +69,11 @@ module Pgbus
         # in_flight counts every claimed message: buffered and running.
         @in_flight = Concurrent::AtomicFixnum.new(0)
         @read_ahead = read_ahead || config.read_ahead
+        # Capsule-level recycle limits (issue #503); each unset key falls back
+        # to the global value at check time, so a config change still applies.
+        @recycle_limits = recycle_limits
+        @capsule = capsule
+        @process = process
         @claim_buffer = ClaimBuffer.new(config: config)
         @loop_tick_at = Concurrent::AtomicReference.new(nil)
         @rate_counter = rate_counter || RateCounter.new(:processed, :failed, :dequeued)
@@ -644,26 +650,33 @@ module Pgbus
       end
 
       def exceeded_max_jobs?
-        return false unless config.max_jobs_per_worker && @jobs_processed.value >= config.max_jobs_per_worker
+        limit = recycle_limit(:max_jobs_per_worker)
+        return false unless limit && @jobs_processed.value >= limit
 
         Pgbus.logger.info { "[Pgbus] Worker recycling: max_jobs reached (#{@jobs_processed.value})" }
         true
       end
 
       def exceeded_max_memory?
-        return false unless config.max_memory_mb && current_memory_mb > config.max_memory_mb
+        limit = recycle_limit(:max_memory_mb)
+        return false unless limit && current_memory_mb > limit
 
-        Pgbus.logger.info { "[Pgbus] Worker recycling: memory limit (#{current_memory_mb}MB > #{config.max_memory_mb}MB)" }
+        Pgbus.logger.info { "[Pgbus] Worker recycling: memory limit (#{current_memory_mb}MB > #{limit}MB)" }
         true
       end
 
       def exceeded_max_lifetime?
-        return false unless config.max_worker_lifetime && (monotonic_now - @started_at_monotonic) > config.max_worker_lifetime
+        limit = recycle_limit(:max_worker_lifetime)
+        return false unless limit && (monotonic_now - @started_at_monotonic) > limit
 
         Pgbus.logger.info { "[Pgbus] Worker recycling: lifetime exceeded" }
         true
       end
 
+      def recycle_limit(key)
+        config.recycle_limit_for(@recycle_limits, key)
+      end
+
       # Instrumentation payload may report a value up to MEMORY_CHECK_TTL seconds old.
       def current_memory_mb
         MemoryUsage.current_mb
@@ -816,10 +829,13 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Heartbeat.new(
           kind: "worker",
+          # capsule/process lead: the dashboard's metadata cell truncates.
           metadata: {
+            capsule: @capsule, process: @process,
             queues: queues, threads: threads, pid: ::Process.pid,
-            execution_mode: @execution_mode, consumer_priority: @consumer_priority
-          },
+            execution_mode: @execution_mode, consumer_priority: @consumer_priority,
+            **lifecycle_metadata
+          }.compact,
           on_beat: -> { on_heartbeat },
           loop_tick_supplier: -> { @loop_tick_at.get },
           metadata_supplier: -> { throughput_metadata }
@@ -860,10 +876,31 @@ module Pgbus
           "jobs_processed" => @jobs_processed.value,
           "jobs_failed" => @jobs_failed.value,
           "in_flight" => @in_flight.value,
-          "buffered" => @claim_buffer.size
+          "buffered" => @claim_buffer.size,
+          **pool_metadata
         }
       end
 
+      # Facts the Processes page states (issue #493), fixed for the process's
+      # life: when it started and which supervisor forked it (ppid; the page
+      # only groups under it when that pid is a supervisor row on this host).
+      def lifecycle_metadata
+        { started_at: @started_at.to_f, supervisor_pid: ::Process.ppid }
+      end
+
+      # Read once per beat: one atomic (threads) or one mutex (async) for the
+      # pool, MemoryUsage's 5s cache for RSS (a ps subprocess on darwin), and
+      # the recycle limits resolved as the recycle check resolves them (a
+      # capsule's own when set), so the page follows a config change.
+      def pool_metadata
+        pool = @pool.metadata
+        {
+          "capacity" => pool[:capacity], "busy" => pool[:busy], "memory_mb" => current_memory_mb,
+          "max_jobs" => recycle_limit(:max_jobs_per_worker), "max_memory_mb" => recycle_limit(:max_memory_mb),
+          "max_lifetime" => recycle_limit(:max_worker_lifetime)
+        }.compact
+      end
+
       def shutdown
         Pgbus.logger.info { "[Pgbus] Worker draining thread pool..." }
         stop_wake_source

data/lib/pgbus/recurring/scheduler.rb

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

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.17.1"
+  VERSION = "0.17.2"
 end

data/lib/pgbus/web/data_source/dashboard_signals.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    class DataSource
+      # The facts behind the home page's words (issue #492): what is retrying
+      # and when it runs next, what died last and why, how the processes and
+      # queues stand, the job rate, and the health verdict /readyz serves.
+      #
+      # summary_stats keeps its shape (the stats API, MetricsSerializer and the
+      # AppSignal probe read it); everything here is home-page only. Each signal
+      # degrades to its empty shape and logs, so one failing query never blanks
+      # the page.
+      module DashboardSignals
+        THROUGHPUT_WINDOW_MINUTES = 5
+
+        EMPTY_RETRYING = { count: 0, capped: false, next_attempt_at: nil, due_now_count: 0,
+                           newest_error_class: nil }.freeze
+
+        def dashboard_signals
+          {
+            retrying: retrying_signal, dlq: dlq_signal, processes: process_signal,
+            queues: queue_signal, throughput: throughput_signal, verdict: verdict_signal
+          }
+        end
+
+        # The Retrying tab of the Jobs page (handler queues left to the Events
+        # page), plus when the next backoff ends, how many are due now and the
+        # newest error among those rows. Each queue contributes its earliest
+        # COUNT_CAP + 1 rows by vt (the vt index), so the next attempt is exact
+        # and the due count is a lower bound past the cap, like the tab counts
+        # (capped: marks both).
+        def retrying_signal
+          counts = job_state_counts(exclude: handler_queue_physical_names)
+          return EMPTY_RETRYING if counts["retrying"].zero?
+
+          schedule = retry_schedule
+          {
+            count: counts["retrying"], capped: counts.capped?("retrying"),
+            next_attempt_at: JobState.time(schedule&.dig("next_at")), due_now_count: schedule&.dig("due").to_i,
+            newest_error_class: schedule&.dig("newest_error")
+          }
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error reading the retry signal: #{e.class}: #{e.message}" }
+          EMPTY_RETRYING
+        end
+
+        # Depth from the cached metrics; the newest message is read from each
+        # non-empty DLQ's tail, so the query stays one index-backed row per DLQ.
+        def dlq_signal
+          counts = dlq_counts_by_queue
+          depth = counts.values.sum
+          { depth: depth, newest: depth.zero? ? nil : newest_dead_letter(counts.select { |_, n| n.positive? }.keys) }
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error reading the dead-letter signal: #{e.class}: #{e.message}" }
+          { depth: depth.to_i, newest: nil }
+        end
+
+        def process_signal
+          rows = processes
+          by_status = rows.group_by { |p| p[:status].to_s }.transform_values(&:size)
+          by_kind = rows.group_by { |p| p[:kind].to_s }.transform_values(&:size)
+          { total: rows.size, healthy: by_status.fetch("healthy", 0), stalled: by_status.fetch("stalled", 0),
+            stale: by_status.fetch("stale", 0), workers: by_kind.fetch("worker", 0),
+            consumers: by_kind.fetch("consumer", 0), dispatchers: by_kind.fetch("dispatcher", 0) }
+        end
+
+        # undrained follows the health verdict: an active (unpaused) backlog on
+        # a job queue no capsule or handler drains. A wildcard drains everything.
+        # depth, claimable and waiting leave the DLQs out (their card counts
+        # them) and the paused queues (paused_depth), whose visible messages
+        # no worker claims.
+        def queue_signal
+          queues = queues_with_metrics
+          dlq, live = queues.partition { |q| q[:name].to_s.end_with?(Pgbus::DEAD_LETTER_SUFFIX) }
+          paused, active = live.partition { |q| q[:paused] }
+          depth = ->(list) { list.sum { |q| q[:queue_length].to_i } }
+          claimable = active.sum { |q| q[:queue_visible_length].to_i }
+          { total: queues.size, paused: paused.size, dlq: dlq.size, undrained: undrained_count(live),
+            depth: depth.call(live), claimable: claimable, waiting: [depth.call(active) - claimable, 0].max,
+            paused_depth: depth.call(paused) }
+        end
+
+        def throughput_signal
+          window = THROUGHPUT_WINDOW_MINUTES
+          return { available: false, jobs_per_minute: nil, window_minutes: window } unless JobStat.table_exists?
+
+          total = JobStat.summary(minutes: window)[:total].to_i
+          { available: true, jobs_per_minute: (total.to_f / window).round(1), window_minutes: window }
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error reading the throughput signal: #{e.class}: #{e.message}" }
+          { available: false, jobs_per_minute: nil, window_minutes: THROUGHPUT_WINDOW_MINUTES }
+        end
+
+        # The verdict /readyz and the MCP serve. The analyzer lives outside
+        # Zeitwerk (pgbus/mcp is ignored), as in HealthApp.
+        def verdict_signal
+          require "pgbus/mcp/health_analyzer" unless defined?(Pgbus::MCP::HealthAnalyzer)
+          Pgbus::MCP::HealthAnalyzer.new(self).verdict
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error computing the health verdict: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        # { physical name => QueueSummary::Line } for the home queues table:
+        # the facts QueueSummary needs for every row, loaded once per render
+        # (pause states in one query, processes and stream names once).
+        def queue_status_lines
+          queues = queues_with_metrics
+          pauses = queue_pause_states(queues.map { |q| q[:name] })
+          healthy = processes.select { |p| p[:healthy] }
+          streams = stream_queue_names
+          max_retries = Pgbus.configuration.max_retries
+          queues.to_h do |q|
+            drainers = queue_drainers(q[:name], healthy: healthy, streams: streams)
+            lines = Web::QueueSummary.present(q, pauses.fetch(q[:name]), drainers, max_retries: max_retries)
+            [q[:name], Web::QueueSummary.headline(lines)]
+          end
+        rescue StandardError => e
+          Pgbus.logger.error { "[Pgbus::Web] Error reading the queue status lines: #{e.class}: #{e.message}" }
+          {}
+        end
+
+        private
+
+        def retry_schedule
+          scope = job_list_scope(nil, exclude: handler_queue_physical_names)
+          return unless scope && scope[:queues].any?
+
+          fragments = scope[:queues].map do |(qtable, logical)|
+            <<~SQL.strip
+              (SELECT m.vt, f.error_class, f.failed_at FROM pgmq.q_#{qtable} m #{failed_join(qtable, logical)}
+               WHERE #{JobList::STATE_PREFILTER["retrying"]} AND (#{JobList::STATE_CASE}) = 'retrying'
+               ORDER BY m.vt LIMIT #{JobList::COUNT_CAP + 1})
+            SQL
+          end
+          connection.select_one(<<~SQL, "Pgbus Retry Schedule")
+            SELECT MIN(vt) FILTER (WHERE vt > now()) AS next_at, COUNT(*) FILTER (WHERE vt <= now()) AS due,
+                   (array_agg(error_class ORDER BY failed_at DESC))[1] AS newest_error
+            FROM (#{fragments.join("\nUNION ALL\n")}) AS retrying
+          SQL
+        end
+
+        def newest_dead_letter(names)
+          fragments = names.map do |name|
+            "(SELECT msg_id, read_ct, enqueued_at, last_read_at, vt, message, headers, '#{sanitize_name(name)}' " \
+              "AS queue_name FROM pgmq.q_#{sanitize_name(name)} ORDER BY msg_id DESC LIMIT 1)"
+          end
+          row = connection.select_one(
+            "SELECT * FROM (#{fragments.join(" UNION ALL ")}) AS newest ORDER BY enqueued_at DESC LIMIT 1",
+            "Pgbus Newest Dead Letter"
+          )
+          row && format_message(row, row["queue_name"])
+        end
+
+        def undrained_count(live)
+          drained = drained_queue_names
+          return 0 if drained.nil?
+
+          backlog = live.reject { |q| q[:paused] || drained.include?(q[:name].to_s) }
+                        .select { |q| q[:queue_visible_length].to_i.positive? }
+          return 0 if backlog.empty?
+
+          streams = stream_queue_names
+          backlog.count { |q| !streams.include?(q[:name].to_s) }
+        end
+      end
+    end
+  end
+end