pgbus 0.9.4 → 0.9.5

data/lib/pgbus/mcp/health_analyzer.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # Computes the top-level pgbus health verdict (OK / DEGRADED / STALLED)
+    # from the existing DataSource read layer. This is the single signal that
+    # catches the silent-worker-wedge class of incident (#179, #174, #181):
+    # a queue with visible messages and no claim progress while a subscribing
+    # worker is heart-beating with idle capacity.
+    #
+    # Verdict semantics (issue #180 acceptance criteria):
+    #   STALLED  — backlog (visible > 0) AND at least one worker is heart-beating
+    #              but its claim loop has stopped advancing (status :stalled),
+    #              OR backlog with live-but-idle workers and zero claim progress.
+    #   DEGRADED — something is wrong but not the wedge: stale processes, a
+    #              paused queue holding a backlog, growing DLQ, or MVCC horizon
+    #              pinned by a long-running transaction.
+    #   OK       — draining normally / nothing actionable.
+    class HealthAnalyzer
+      # A worker is considered to have idle capacity unless its metadata
+      # explicitly reports it is saturated. We treat the presence of any live
+      # worker as "has capacity" because a wedged worker reports healthy
+      # heartbeats while doing no work — exactly the case we must catch.
+      WORKER_KIND = "worker"
+
+      def initialize(data_source)
+        @data_source = data_source
+      end
+
+      # Returns a machine-readable verdict hash suitable for both interactive
+      # agent use and automated alerting.
+      def verdict
+        queues          = @data_source.queues_with_metrics
+        processes       = @data_source.processes
+        health, health_error = safe_queue_health
+
+        # Partition queues once: non-DLQ (the operational set) and the subset
+        # of those with visible, claimable backlog. Paused queues are removed
+        # from the STALLED backlog (an intentional pause is not the wedge —
+        # it's reported under DEGRADED), but kept in `non_dlq` for the summary.
+        non_dlq = queues.reject { |q| dlq?(q) }
+        backlog = non_dlq.select { |q| q[:queue_visible_length].to_i.positive? }
+        active_backlog = backlog.reject { |q| q[:paused] }
+
+        stalled  = stalled_reasons(active_backlog, processes)
+        degraded = degraded_reasons(queues, backlog, processes, health, health_error)
+
+        status = if stalled.any?
+                   "STALLED"
+                 elsif degraded.any?
+                   "DEGRADED"
+                 else
+                   "OK"
+                 end
+
+        {
+          status: status,
+          reasons: stalled + degraded,
+          checked_at: Time.now.utc.iso8601,
+          summary: build_summary(queues, non_dlq, processes, health)
+        }
+      end
+
+      private
+
+      def dlq?(queue)
+        queue[:name].to_s.end_with?(Pgbus::DEAD_LETTER_SUFFIX)
+      end
+
+      # Returns [health_hash, error_or_nil]. We never raise — pgbus_health
+      # must always produce a verdict — but we DO surface the failure so the
+      # caller knows the verdict was built from partial data, and we log it
+      # for operators (per the project's no-silent-errors rule).
+      def safe_queue_health
+        [@data_source.queue_health_stats, nil]
+      rescue StandardError => e
+        Pgbus.logger.warn { "[Pgbus::MCP] queue_health_stats failed: #{e.class}: #{e.message}" }
+        [{}, e]
+      end
+
+      # STALLED detection: an active (non-paused) backed-up queue while a
+      # worker is in the :stalled state, or backed up with live-but-idle
+      # workers present.
+      def stalled_reasons(backlog, processes)
+        return [] if backlog.empty?
+
+        workers = processes.select { |p| p[:kind] == WORKER_KIND }
+        return [] if workers.empty?
+
+        stalled_workers = workers.select { |w| w[:status].to_s == "stalled" }
+        live_workers    = workers.select { |w| %w[healthy stalled].include?(w[:status].to_s) }
+
+        reasons = []
+        if stalled_workers.any?
+          reasons << "#{stalled_workers.size} worker(s) stalled (heart-beating but claim loop not advancing) " \
+                     "while #{backlog.size} queue(s) have visible backlog: #{backlog_names(backlog)}"
+        elsif live_workers.any? && all_unread?(backlog)
+          reasons << "#{backlog.size} queue(s) have visible messages with read_ct=0 (never claimed) " \
+                     "while #{live_workers.size} worker(s) are alive: #{backlog_names(backlog)}"
+        end
+        reasons
+      end
+
+      # DEGRADED detection: conditions worth surfacing that are not the wedge.
+      def degraded_reasons(queues, backlog, processes, health, health_error)
+        reasons = []
+
+        reasons << "queue health stats unavailable: #{health_error.class}: #{health_error.message}" if health_error
+
+        stale = processes.select { |p| p[:status].to_s == "stale" }
+        reasons << "#{stale.size} process(es) stale (no recent heartbeat)" if stale.any?
+
+        paused_backlog = backlog.select { |q| q[:paused] }
+        reasons << "#{paused_backlog.size} paused queue(s) holding a backlog: #{backlog_names(paused_backlog)}" if paused_backlog.any?
+
+        dlq = queues.select { |q| dlq?(q) && q[:queue_length].to_i.positive? }
+        reasons << "#{dlq.size} dead-letter queue(s) hold messages" if dlq.any?
+
+        age = health[:oldest_transaction_age_sec]
+        reasons << "oldest open transaction is #{age}s old (MVCC horizon pinning risk)" if age && age > 300
+
+        reasons
+      end
+
+      # The strongest wedge signal: visible messages that have never been read.
+      # When queue metrics don't expose read_ct we conservatively treat the
+      # backlog as unread (the wedge default) so we don't miss the condition.
+      def all_unread?(backlog)
+        backlog.all? { |q| !q.key?(:max_read_ct) || q[:max_read_ct].to_i.zero? }
+      end
+
+      def backlog_names(queues)
+        queues.map { |q| q[:name] }.join(", ")
+      end
+
+      def build_summary(queues, non_dlq, processes, health)
+        workers = stale = stalled = 0
+        processes.each do |p|
+          status = p[:status].to_s
+          stale += 1 if status == "stale"
+          next unless p[:kind] == WORKER_KIND
+
+          workers += 1
+          stalled += 1 if status == "stalled"
+        end
+
+        {
+          queues: queues.size,
+          total_visible: non_dlq.sum { |q| q[:queue_visible_length].to_i },
+          total_depth: non_dlq.sum { |q| q[:queue_length].to_i },
+          workers: workers,
+          stalled_workers: stalled,
+          stale_processes: stale,
+          oldest_transaction_age_sec: health[:oldest_transaction_age_sec]
+        }
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/rack_app.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # A turnkey, gated Rack app that serves the read-only pgbus diagnostic MCP
+    # server over HTTP. Mount it inside your existing Rails app — no second
+    # process, same DB credentials, same connection pool:
+    #
+    #   # config/routes.rb
+    #   mount Pgbus::MCP.rack_app(token: ENV["PGBUS_MCP_TOKEN"]) => "/pgbus/mcp"
+    #
+    # The underlying transport runs in stateless + JSON-response mode, which:
+    #   * makes every request a self-contained POST returning a single JSON
+    #     object (no in-memory session, no SSE stream, no reaper thread), so it
+    #     is safe behind multiple Puma/Falcon workers — any worker can answer
+    #     any request;
+    #   * is exactly what a read-only diagnostic server needs (it never pushes
+    #     server-initiated messages to the client).
+    #
+    # Security: requests are rejected with 401 unless they carry the configured
+    # token (or pass the supplied auth callable). Run it on an internal network
+    # / behind your VPN, never internet-exposed.
+    class RackApp
+      BEARER_PREFIX = "Bearer "
+      UNAUTHORIZED = [
+        401,
+        { "Content-Type" => "application/json", "WWW-Authenticate" => "Bearer" },
+        [{ jsonrpc: "2.0", id: nil, error: { code: -32_001, message: "Unauthorized" } }.to_json]
+      ].freeze
+
+      # @param data_source [Pgbus::Web::DataSource] read layer the tools query.
+      #   Built once and shared: DataSource acquires Pgbus::BusRecord.connection
+      #   from the ActiveRecord pool on each call, so a single instance is
+      #   request-safe across threads/workers.
+      # @param allow_payloads [Boolean] when true, tools honor a per-call
+      #   include_payloads flag; otherwise message bodies are always redacted.
+      # @param token [String, nil] shared secret. When present, requests must
+      #   send `Authorization: Bearer <token>`. nil disables the built-in gate.
+      # @param auth [#call, nil] custom authenticator taking a Rack::Request and
+      #   returning truthy to allow. Mirrors Pgbus.configuration.web_auth. Takes
+      #   precedence over +token+ when both are given.
+      def initialize(data_source: Pgbus::Web::DataSource.new, allow_payloads: false, token: nil, auth: nil)
+        @token = token
+        @auth = auth
+        @server = Server.build(data_source: data_source, allow_payloads: allow_payloads)
+        @transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(
+          @server, stateless: true, enable_json_response: true
+        )
+        warn_unauthenticated! if @token.nil? && @auth.nil?
+      end
+
+      # Mount THIS object, never the bare transport. The auth gate lives here
+      # and runs before handle_request for *every* HTTP method (POST/GET/
+      # DELETE/...). Mounting @transport directly would skip authorization —
+      # the gem's transport has no auth of its own.
+      def call(env)
+        request = Rack::Request.new(env)
+        return UNAUTHORIZED unless authorized?(request)
+
+        @transport.handle_request(request)
+      end
+
+      private
+
+      # An explicit auth callable wins; otherwise fall back to the bearer token;
+      # otherwise (neither configured) allow — the constructor already warned.
+      def authorized?(request)
+        return !!@auth.call(request) if @auth
+        return bearer_matches?(request) if @token
+
+        true
+      end
+
+      def bearer_matches?(request)
+        header = request.get_header("HTTP_AUTHORIZATION").to_s
+        return false unless header.start_with?(BEARER_PREFIX)
+
+        Runner.secure_compare?(@token, header.delete_prefix(BEARER_PREFIX))
+      end
+
+      def warn_unauthenticated!
+        Pgbus.logger.warn do
+          "[Pgbus::MCP] HTTP diagnostic server mounted without authentication. " \
+            "Pass token: or auth: to Pgbus::MCP.rack_app, and keep it on an internal network."
+        end
+      end
+    end
+
+    module_function
+
+    # Build a gated Rack app serving the read-only diagnostic tools over HTTP.
+    # See {RackApp} for the parameters and deployment guidance.
+    def rack_app(data_source: Pgbus::Web::DataSource.new, allow_payloads: false, token: nil, auth: nil)
+      RackApp.new(data_source: data_source, allow_payloads: allow_payloads, token: token, auth: auth)
+    end
+  end
+end

data/lib/pgbus/mcp/redactor.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # Strips message bodies / headers / job arguments from tool responses
+    # before they leave the process. Job payloads can carry PII or secrets, so
+    # the diagnostic tools return metadata (ids, counts, ages, read_ct, vt,
+    # queue names, job_class) by default and only include the raw payload when
+    # an explicit, separately-gated flag is set.
+    #
+    # +deep_redact+ is applied centrally at the response boundary
+    # (BaseTool.json_response), so redaction is fail-safe: a tool author cannot
+    # leak a payload by forgetting to redact — they have to opt in.
+    #
+    # See issue #180: "No sensitive payload leakage — diagnostic tools should
+    # return metadata ... and redact or omit message payloads unless an
+    # explicit, separately-gated flag is set."
+    module Redactor
+      module_function
+
+      # Keys whose values are message bodies / headers and must never be
+      # returned unless payloads are explicitly allowed.
+      PAYLOAD_KEYS = %i[message headers payload arguments].freeze
+
+      # Replacement marker so the agent can see a field exists but was hidden,
+      # rather than the field silently vanishing.
+      REDACTED = "[redacted]"
+
+      # True if +key+ names a payload-bearing field. Tolerates string or symbol
+      # keys and never raises on a non-symbolizable key.
+      def payload_key?(key)
+        PAYLOAD_KEYS.include?(key.respond_to?(:to_sym) ? key.to_sym : key)
+      end
+
+      # Recursively redact payload-bearing keys anywhere in a nested structure
+      # of hashes and arrays. This is the fail-safe applied at the response
+      # boundary (BaseTool.json_response): a tool that returns a payload key —
+      # at any depth, even one its author forgot about — has it stripped unless
+      # payloads are explicitly allowed for the call.
+      #
+      # A payload key is redacted only when its value is a leaf (the serialized
+      # message body / headers string). When the value is a Hash or Array the
+      # key is an envelope (e.g. a {message: {...}} detail wrapper, not a raw
+      # body), so we descend into it instead of blanking the whole subtree.
+      def deep_redact(value, include_payloads: false)
+        return value if include_payloads
+
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), result|
+            result[key] =
+              if payload_key?(key) && leaf?(nested) && !nested.nil?
+                REDACTED
+              else
+                deep_redact(nested, include_payloads: include_payloads)
+              end
+          end
+        when Array
+          value.map { |element| deep_redact(element, include_payloads: include_payloads) }
+        else
+          value
+        end
+      end
+
+      # A leaf is anything that isn't a structure we recurse into — i.e. the
+      # actual serialized payload value rather than an envelope hash/array.
+      def leaf?(value)
+        !value.is_a?(Hash) && !value.is_a?(Array)
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/runner.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "active_support/security_utils"
+
+module Pgbus
+  module MCP
+    # Boots the pgbus diagnostic MCP server over stdio. This is what
+    # `pgbus mcp` invokes. Separated from Server so the server assembly stays
+    # transport-agnostic and unit-testable without touching $stdin/$stdout.
+    #
+    # Security posture (issue #180):
+    #   * Never starts unless explicitly invoked (`pgbus mcp`).
+    #   * Reuses the app's existing DB connection/config — no new privileged
+    #     path is opened.
+    #   * Payloads are redacted unless PGBUS_MCP_ALLOW_PAYLOADS is truthy.
+    #   * Optional token gate: when PGBUS_MCP_TOKEN is set, the same value must
+    #     be present in PGBUS_MCP_AUTH_TOKEN at boot or the server refuses to
+    #     start. stdio is a local, parent-spawned channel, so the gate is a
+    #     boot-time precondition rather than a per-message header.
+    module Runner
+      TRUTHY = %w[1 true yes on].freeze
+
+      module_function
+
+      # Build the server, enforce the optional token gate, and drive the stdio
+      # transport until the client disconnects.
+      #
+      # @param env [Hash] environment to read flags from (injectable for tests).
+      def run(env: ENV)
+        authorize!(env)
+
+        allow_payloads = truthy?(env["PGBUS_MCP_ALLOW_PAYLOADS"])
+        server = Server.build(allow_payloads: allow_payloads)
+        transport = ::MCP::Server::Transports::StdioTransport.new(server)
+        log_start(allow_payloads)
+        transport.open
+      end
+
+      # Raise unless the configured token matches. No-op when PGBUS_MCP_TOKEN
+      # is unset (token gating is opt-in).
+      def authorize!(env)
+        expected = env["PGBUS_MCP_TOKEN"]
+        return if expected.nil? || expected.empty?
+
+        provided = env["PGBUS_MCP_AUTH_TOKEN"]
+        return if secure_compare?(expected, provided)
+
+        raise Pgbus::Error,
+              "pgbus MCP: authentication failed. PGBUS_MCP_TOKEN is set; provide a matching PGBUS_MCP_AUTH_TOKEN."
+      end
+
+      def truthy?(value)
+        TRUTHY.include?(value.to_s.strip.downcase)
+      end
+
+      # Constant-time comparison to avoid leaking the token via timing.
+      # Delegates to ActiveSupport's vetted implementation (railties already
+      # pulls in active_support). secure_compare handles unequal lengths
+      # safely — it compares fixed-length SHA256 digests, then verifies the
+      # raw values match — so it never raises on a length mismatch.
+      def secure_compare?(expected, provided)
+        return false if provided.nil?
+
+        ActiveSupport::SecurityUtils.secure_compare(expected, provided)
+      end
+
+      def log_start(allow_payloads)
+        mode = allow_payloads ? "payloads ALLOWED" : "payloads redacted"
+        Pgbus.logger.info { "[Pgbus::MCP] starting read-only diagnostic server over stdio (#{mode})" }
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/server.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # Assembles the read-only pgbus diagnostic MCP server: registers every
+    # diagnostic tool and wires a DataSource (plus the payload gate) into the
+    # server context so tools never touch the database directly or leak
+    # payloads by default.
+    #
+    # This class only builds the +MCP::Server+ instance — transport is the
+    # caller's concern (Runner drives stdio). Keeping them separate means the
+    # same server can later be mounted over HTTP without changing tool code.
+    module Server
+      # The fixed, curated tool set. No arbitrary-SQL tool, no mutation tool —
+      # adding one here would violate the issue #180 security contract.
+      TOOLS = [
+        Tools::HealthTool,
+        Tools::QueuesTool,
+        Tools::QueueDetailTool,
+        Tools::ProcessesTool,
+        Tools::JobsTool,
+        Tools::JobDetailTool,
+        Tools::DlqTool,
+        Tools::DlqDetailTool,
+        Tools::LocksTool,
+        Tools::ThroughputTool,
+        Tools::StatsTool,
+        Tools::RecurringTool
+      ].freeze
+
+      INSTRUCTIONS = <<~TEXT
+        Read-only diagnostic tools for a pgbus (PostgreSQL/PGMQ) deployment.
+        Start with pgbus_health for a one-call OK/DEGRADED/STALLED verdict,
+        then drill in with pgbus_queues, pgbus_processes, pgbus_jobs,
+        pgbus_dlq, and pgbus_locks. No tool mutates state. Message payloads
+        are redacted unless the server was started with payloads explicitly
+        allowed.
+      TEXT
+
+      module_function
+
+      # Build an MCP::Server with all diagnostic tools registered.
+      #
+      # @param data_source [Pgbus::Web::DataSource] read layer the tools query.
+      # @param allow_payloads [Boolean] when true, tools honor a per-call
+      #   include_payloads flag; otherwise payloads are always redacted.
+      def build(data_source: Pgbus::Web::DataSource.new, allow_payloads: false)
+        ::MCP::Server.new(
+          name: "pgbus",
+          title: "Pgbus Diagnostics",
+          version: Pgbus::VERSION,
+          instructions: INSTRUCTIONS,
+          tools: TOOLS.dup,
+          server_context: {
+            data_source: data_source,
+            allow_payloads: allow_payloads
+          }
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Inspect a single dead-letter message. Maps to DataSource#job_detail
+      # against the named DLQ queue when +queue+ is supplied; falls back to a
+      # cross-DLQ scan via DataSource#dlq_message_detail when it is not.
+      # Payload redacted by default.
+      class DlqDetailTool < BaseTool
+        tool_name "pgbus_dlq_detail"
+        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.
+          "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
+          returns the FIRST match, which is ambiguous when multiple DLQs
+          contain the id and is reported as an error. The message body and
+          headers are redacted unless the server allows payloads and
+          include_payloads is set.
+        DESC
+
+        input_schema(
+          properties: {
+            queue: {
+              type: "string",
+              description: "Full physical DLQ queue name (e.g. \"pgbus_default_dlq\"). Strongly recommended."
+            },
+            msg_id: { type: "integer", description: "Numeric PGMQ message id." },
+            include_payloads: {
+              type: "boolean",
+              description: "Include the raw message body/headers. Only honored when the server allows payloads."
+            }
+          },
+          required: %w[msg_id]
+        )
+
+        def self.call(msg_id:, queue: nil, include_payloads: false, server_context: nil)
+          data_source = data_source_from(server_context)
+          detail =
+            if queue
+              data_source.job_detail(queue, msg_id)
+            else
+              ambiguity_check(data_source, msg_id) || data_source.dlq_message_detail(msg_id)
+            end
+          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)
+        end
+
+        # When the caller didn't specify a queue, scan every DLQ for the id and
+        # refuse to guess if more than one matches. Returns an error response
+        # on ambiguity, nil otherwise (so the caller proceeds with the normal
+        # first-match lookup).
+        def self.ambiguity_check(data_source, msg_id)
+          dlq_suffix = Pgbus::DEAD_LETTER_SUFFIX
+          dlqs = data_source.queues_with_metrics.select { |q| q[:name].to_s.end_with?(dlq_suffix) }
+          matches = dlqs.map { |q| q[:name] }.select { |name| data_source.job_detail(name, msg_id) }
+          return nil if matches.size <= 1
+
+          error_response(
+            "Dead-letter message #{msg_id} is ambiguous — present in #{matches.size} DLQs " \
+            "(#{matches.join(", ")}). Pass `queue:` to disambiguate."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Paginated dead-letter queue inspection across all *_dlq queues.
+      # Maps to DataSource#dlq_messages. Payloads redacted by default.
+      class DlqTool < BaseTool
+        tool_name "pgbus_dlq"
+        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.
+        DESC
+
+        MAX_PER_PAGE = 100
+        MAX_PAGE = 1_000
+
+        input_schema(
+          properties: {
+            page: { type: "integer", description: "1-based page number (default 1).", minimum: 1 },
+            per_page: { type: "integer", description: "Rows per page (default 25, max 100).", minimum: 1 },
+            include_payloads: {
+              type: "boolean",
+              description: "Include raw message bodies/headers. Only honored when the server allows payloads."
+            }
+          },
+          required: []
+        )
+
+        def self.call(page: 1, per_page: 25, include_payloads: false, server_context: nil)
+          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)
+
+          json_response(
+            { page: page, per_page: per_page, messages: rows },
+            server_context: server_context,
+            include_payloads: include_payloads
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Top-level health verdict: OK / DEGRADED / STALLED, with the reasons
+      # that drove it. Delegates the actual analysis to HealthAnalyzer, which
+      # reads the same DataSource surface the dashboard uses. This is the
+      # single tool that catches the silent-worker-wedge class of incident.
+      class HealthTool < BaseTool
+        tool_name "pgbus_health"
+        title "Pgbus Health"
+        description <<~DESC
+          Top-level pgbus health verdict. Returns OK, DEGRADED, or STALLED with
+          the specific reasons. STALLED means the silent-wedge condition:
+          queues have visible backlog while workers are heart-beating but not
+          claiming (or a worker's claim loop has stalled). DEGRADED covers
+          stale processes, paused queues holding a backlog, dead-letter
+          buildup, or a long-running transaction pinning the MVCC horizon. Use
+          this first when triaging — it summarizes the whole system in one call
+          and is suitable for automated alerting.
+        DESC
+
+        input_schema(properties: {}, required: [])
+
+        def self.call(server_context: nil)
+          data_source = data_source_from(server_context)
+          json_response(HealthAnalyzer.new(data_source).verdict)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Inspect a single enqueued message by queue + msg_id. Returns its
+      # metadata (read_ct, vt, enqueued_at, last_read_at); the body and headers
+      # are redacted unless payloads are explicitly allowed. Maps to
+      # DataSource#job_detail.
+      class JobDetailTool < BaseTool
+        tool_name "pgbus_job_detail"
+        title "Pgbus Job Detail"
+        description <<~DESC
+          Inspect one enqueued message: read_ct, visibility timeout (vt),
+          enqueued_at, last_read_at. Pass the full physical queue name and the
+          numeric msg_id. The message body and headers are redacted unless the
+          server allows payloads and include_payloads is set.
+        DESC
+
+        input_schema(
+          properties: {
+            queue: { type: "string", description: "Full physical queue name (e.g. \"pgbus_default\")." },
+            msg_id: { type: "integer", description: "Numeric PGMQ message id." },
+            include_payloads: {
+              type: "boolean",
+              description: "Include the raw message body/headers. Only honored when the server allows payloads."
+            }
+          },
+          required: %w[queue msg_id]
+        )
+
+        def self.call(queue:, msg_id:, include_payloads: false, server_context: nil)
+          data_source = data_source_from(server_context)
+          detail = data_source.job_detail(queue, msg_id)
+          return error_response("Message #{msg_id} not found in #{queue}") unless detail
+
+          json_response({ job: detail }, server_context: server_context, include_payloads: include_payloads)
+        end
+      end
+    end
+  end
+end