pgbus 0.12.4 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 916f349cd5f3740aca0e462acdadeb3ad7322b0ce8f0363fa78d2328ac3c7c37
-  data.tar.gz: 13100607efcb25262f7d4708355d600009aff7f66e961d197d00fe2013ab9a88
+  metadata.gz: 8c955f8fb2ac4e66fb2db388505ee83341aa6dec7c00f606162f7fba7c29cb75
+  data.tar.gz: a31e43c6f48cb10609d73dc507e9d177d25a299ae25c6f5d5a39a045018c32e8
 SHA512:
-  metadata.gz: 325b359be3de92b27add05e70ac9437b813df2e464ad1ceca2fbd3fe2114c4a52471e7e5f23564765e74d6c8330068cf0d9ab9ccaddd9443d98ab69088a1ee34
-  data.tar.gz: 5fb4ee93c03a463cddcfa490a438ae6d267fc12a23c633a7ee82f45754fde6232a23f5da2772df45f4653efbee4018b7b336adb79f50bf4e1ccc0438c4718971
+  metadata.gz: 7cd3fba720a5ab724fe4f0b5b89168cb2df4ba68e0a5a35cca725093724f8f2b2109c379a2263442111367001a52d2eda440eef8e1c2469653d2022d2a92d148
+  data.tar.gz: 4a4e5e1c2c229c599541e61ac6ad5602dfbfcf057b346b22b0271c10a48752c41075c7166b43dd55ece7ef4a30d79ec3fd6f5cac5b898b2578ecb90c73bcc2a8

data/CHANGELOG.md

@@ -1,7 +1,17 @@
 ## [Unreleased]
 
+### Added
+
+- **Streams: one LISTEN connection per web host — `streams_listen_scope` (issue #382).** ⚠️ **Default behavior change.** Previously every Puma worker lazily opened its own dedicated streams LISTEN connection on first SSE use, so a web host pinned one direct connection per worker. Under the new default (`streams_listen_scope = :master`) the `pgbus_streams` Puma plugin runs a **MasterHub** in the preforking master: ONE `Web::Streamer::Listener` on the refcounted union of every worker's stream channels, fanning wakes — **including ephemeral payloads** — out to workers over a Unix domain socket with length-prefixed frames (`Streamer::HubProtocol`). Workers connect lazily (nothing is inherited across fork) and the synchronous `ensure_listening` ack contract is preserved cross-process: a sub is registered before LISTEN executes and acked only after, so the no-lost-broadcast guarantee holds. Backpressure follows the streams rules: durable wakes are droppable at a per-worker cap (they self-heal via `read_after`), **ephemeral wakes are never dropped** — a worker that stops draining is evicted, which triggers its own fallback. **Fallback is per-worker listeners, not loss**: whenever the hub is absent or dies (no `preload_app!`, single-mode Puma, crash, eviction) each worker's `FailoverListener` swaps in a real per-worker `Listener` and re-LISTENs its recorded subscriptions — connection footprint balloons back to pre-#382 levels (census-visible) but no broadcast semantics change; the worker stays local until it recycles. Measured (local PG, n=50): the master→worker hop is noise-level free — single-broadcast SSE roundtrip p50 16.00ms via the hub vs 16.93ms per-worker. **`:master` effectively requires `preload_app!`** (the hub waits for the app's pgbus initializer; without it the deadline expires quietly and workers stay per-worker). **Rollback:** `config.streams_listen_scope = :process`. Refs #382, builds on the #381 patterns.
+
+- **Host-level shared LISTEN: `worker_notify_scope` — the supervisor now owns ONE direct LISTEN connection for the whole host (issue #381).** ⚠️ **Default behavior change.** Previously every worker fork and every consumer fork opened its own dedicated LISTEN connection (`NotifyListener`), so a host's direct-connection footprint scaled with fork count — on transaction-pool PgBouncer platforms those connections come out of the scarcest slice of `max_connections`, and a 5-capsule + 2-consumer host pinned 7. Under the new default (`config.worker_notify_scope = :supervisor`) the supervisor runs a single `NotifyHub`: one `NotifyListener` on the union of every capsule's and consumer's queue channels (wildcards via the shared resolver, consumer sets via the registry), fanning wakes out to forks over per-fork pipes (`W` wake / `H` healthy / `P` degraded bytes; a fork whose pipe reports degraded or reaches EOF falls back to fast polling exactly like a failed local listener). Footprint drops to **1 direct LISTEN connection per job host**, verified by integration test: routing is per-fork (an insert wakes only the forks reading that queue, wildcard capsules unconditionally), and `pg_terminate_backend` on the shared connection is survived — reconnect, re-LISTEN, wakes flow again. **Rollback:** `config.worker_notify_scope = :fork` restores the previous per-fork listeners byte-for-byte. Dedicated LISTEN connections are now census-tagged `application_name=pgbus-listen` so `pg_stat_activity` can count them. Refs #381.
+- **`pgbus doctor`: new "Connection budget" check (issue #381).** Prints how many direct LISTEN connections the current config pins — 1 per host under `:supervisor` scope, capsules + consumers under `:fork` (honoring `config.roles`), plus a "+1 per web-server process (streams)" clause — so operators can do pooler capacity math from the doctor output alone. Informational, always `:ok`. Refs #381.
+- **Benchmarks: `rake bench:notify_wake` and `rake bench:notify_chaos` (issue #381).** Wake-path latency (send → wake, p50/p95/p99, direct vs hub-mediated), empty-read cost, LISTEN connection census, and failure-mode measurements (killed LISTEN backend, wedged fork, FD churn, fan-out cost). Refs #381.
+
 ### Changed
 
+- **Multi-queue strict-priority contract documented and pinned (issue #381).** The capsule DSL's "list order = strict priority" promise rides on Postgres's Append node filling `read_multi`'s `UNION ALL … LIMIT` from earlier-listed subqueries first — incidental behavior nothing upstream promises. The contract (and the vt-claim caveat: subquery rows discarded by the outer LIMIT are still claimed and go invisible for one visibility timeout) is now documented on `Client#read_multi` and the capsule DSL, and pinned by an integration canary (`spec/integration/multi_queue_priority_spec.rb`) so a planner or pgmq-ruby change breaks loudly instead of silently. `Consumer#wake_timeout` also gained the live-but-deaf listener consult (`delivering?`) for parity with Worker (issue #332). Refs #381.
+
 - **README: doctor table and configuration reference catch up to the shipped surface (issue #369).** The doctor section still said "six checks" and listed only the original six; `Pgbus::Doctor::CHECKS` has 10 (GlobalID allowlist, Broadcast queue, Primary affinity, Dedicated connections were missing — the first two are the ones most likely to warn after upgrade on nil defaults). The configuration reference table was missing ~20 shipped options operators actually hit: `allowed_global_id_models` (incl. `[]` = deny-all), streams GC (`streams_orphan_threshold` / `streams_orphan_sweep_interval` — 24h / hourly defaults that auto-drop dormant durable stream queues), retention/durable/presence/broadcast-queue knobs, `streams_pool_*` / LISTEN connection overrides, `doctor_on_boot`, `require_primary`, `connects_to`, `zombie_detection`, `connection_guc_mode`, `worker_notify_*`, `group_mode`, and neighbors. A unit drift guard pins the README doctor table to every `Doctor::CHECKS` name. Full typed reference remains on the docs site. Refs #369.
 
 ### Fixed

data/README.md

@@ -1862,7 +1862,7 @@ pgbus help      # Show help
 
 #### pgbus doctor
 
-A single preflight command that answers "is this environment healthy enough to run?" — useful as a deploy or CI gate. It runs 10 checks and never raises; a broken environment turns every probe into a failed/warned check instead of a crash:
+A single preflight command that answers "is this environment healthy enough to run?" — useful as a deploy or CI gate. It runs 11 checks and never raises; a broken environment turns every probe into a failed/warned check instead of a crash:
 
 | Check | Fails (`:fail`) when | Warns (`:warn`) when |
 |---|---|---|
@@ -1876,6 +1876,7 @@ A single preflight command that answers "is this environment healthy enough to r
 | Broadcast queue | — | Turbo broadcasts share the default queue in production, or `streams_broadcast_queue` is set but no worker capsule drains it |
 | Primary affinity | — | Job connection is on a read-only replica (`pg_is_in_recovery`) — a read/write-splitting pooler may be stalling jobs |
 | Dedicated connections | Streamer LISTEN and/or worker notify dedicated path cannot connect | — |
+| Connection budget | — (informational: prints how many direct LISTEN connections the current config pins — 1 per host under `worker_notify_scope: :supervisor`, one per fork under `:fork`; streams add 1 per web host under `streams_listen_scope: :master` or 1 per web process under `:process`) | — |
 
 ```bash
 pgbus doctor       # prints the report; exit 1 unless every check passed

data/Rakefile

@@ -24,7 +24,8 @@ namespace :bench do
   # Benches that need a real PostgreSQL/PGMQ (or boot Puma) — excluded from the
   # no-DB unit suite that bench:all runs in CI.
   db_benches = %w[connection_pool_bench integration_bench streams_bench streams_read_pool_bench
-                  execution_modes_bench pool_swap_bench pool_autoscale_bench job_burst_bench].freeze
+                  execution_modes_bench pool_swap_bench pool_autoscale_bench job_burst_bench
+                  notify_wake_bench notify_chaos_bench streams_hub_bench].freeze
   # The unit suite is every *_bench.rb that doesn't need a database, derived
   # from the directory so a new unit bench is picked up automatically (kept in
   # sync with bench:one, which globs the same files).
@@ -84,6 +85,21 @@ namespace :bench do
     ruby "benchmarks/job_burst_bench.rb"
   end
 
+  desc "Run NOTIFY wake-path benchmark (#381 wake latency + connection census; requires PGBUS_DATABASE_URL)"
+  task :notify_wake do
+    ruby "benchmarks/notify_wake_bench.rb"
+  end
+
+  desc "Run NotifyHub failure-mode measurements (#381 chaos scenarios; requires PGBUS_DATABASE_URL)"
+  task :notify_chaos do
+    ruby "benchmarks/notify_chaos_bench.rb"
+  end
+
+  desc "Run streams master-hub latency benchmark (#382 hop cost + census; requires PGBUS_DATABASE_URL)"
+  task :streams_hub do
+    ruby "benchmarks/streams_hub_bench.rb"
+  end
+
   desc "Run a single benchmark: rake bench:one[client_bench]"
   task :one, [:name] do |_t, args|
     name = args[:name] or abort "Usage: rake bench:one[serialization_bench|client_bench|...]"

data/lib/pgbus/client.rb

@@ -434,6 +434,21 @@ module Pgbus
     # caller receives up to `queue_count * qty` messages. Pass `limit:` to cap
     # the total across all queues — required when feeding a fixed-size pool,
     # otherwise the pool can overflow on multi-queue reads (issue #123).
+    #
+    # STRICT-PRIORITY CONTRACT (issue #381): when `limit:` is smaller than the
+    # total available, earlier-listed queues win — the capsule DSL's "list
+    # order = strict priority" promise rides on this. The mechanism is
+    # incidental: pgmq-ruby builds `pgmq.read(q1) UNION ALL pgmq.read(q2) …
+    # LIMIT n`, and Postgres's Append node fills the LIMIT from the subqueries
+    # in written order. Nothing upstream promises that, so the contract is
+    # pinned by spec/integration/multi_queue_priority_spec.rb — if that canary
+    # ever breaks, switch callers to ordered per-queue reads (the
+    # Worker#fetch_prioritized pattern) instead of relying on this method.
+    #
+    # vt-claim caveat: each subquery may claim (set vt on) up to `qty` rows
+    # even when the outer LIMIT discards them — a discarded row goes invisible
+    # for one visibility timeout without being processed. Size `qty`/`limit`
+    # accordingly on latency-sensitive queues.
     def read_multi(queue_names, qty:, vt: nil, limit: nil)
       full_names = queue_names.map { |q| config.queue_name(q) }
       guarded_read do

data/lib/pgbus/configuration/capsule_dsl.rb

@@ -19,6 +19,14 @@ module Pgbus
     #   *    wildcard, matches all queues
     #   *_   trailing wildcard, prefix match (e.g. "staging_*")
     #
+    # "List order = strict priority" is enforced two ways at runtime: with
+    # priority_levels > 1 the worker reads queues one at a time in list order
+    # (Worker#fetch_prioritized); otherwise it relies on Client#read_multi's
+    # UNION ALL filling its LIMIT from earlier-listed queues first — an
+    # Append-node behavior Postgres does not formally promise, pinned by
+    # spec/integration/multi_queue_priority_spec.rb (see Client#read_multi
+    # for the contract and its vt-claim caveat).
+    #
     # Returns +Array<Hash>+ in the same shape as the legacy +workers:+ array,
     # so the rest of the codebase can consume it without changes:
     #

data/lib/pgbus/configuration.rb

@@ -179,14 +179,22 @@ module Pgbus
                   :streams_pool_autoscale_interval, :streams_application_name
     attr_reader :streams_default_broadcast_mode # rubocop:disable Style/AccessorGrouping
 
-    # NOTIFY-gated worker wakeups. When true, each Worker fork owns a
-    # dedicated NotifyListener PG connection that LISTENs on its queues'
-    # INSERT channels and wakes the loop on a real insert. Defaults to the
-    # value of listen_notify. The worker_notify_* overrides mirror
-    # streams_* so the LISTEN connection can bypass PgBouncer.
+    # NOTIFY-gated worker wakeups. When true, workers are woken by a
+    # NotifyListener PG connection that LISTENs on their queues' INSERT
+    # channels instead of blind-polling. Defaults to the value of
+    # listen_notify. The worker_notify_* overrides mirror streams_* so the
+    # LISTEN connection can bypass PgBouncer.
     attr_accessor :worker_notify_wakeup,
                   :worker_notify_host, :worker_notify_port, :worker_notify_database_url
 
+    # Where the LISTEN connection lives (issue #381):
+    #   :supervisor (default) — ONE shared NotifyListener in the supervisor
+    #     process for the whole host; forks are woken over per-fork pipes.
+    #     Direct-connection footprint: 1, regardless of capsule/consumer count.
+    #   :fork — one NotifyListener (and one dedicated PG connection) per
+    #     worker/consumer fork: the pre-0.13 behavior, kept as an escape hatch.
+    attr_reader :worker_notify_scope
+
     # AppSignal integration (auto-loaded when ::Appsignal is defined and this is true).
     # Set to false to opt out without uninstalling the appsignal gem.
     attr_accessor :appsignal_enabled, :appsignal_probe_enabled
@@ -261,6 +269,8 @@ module Pgbus
       @listen_notify = true
 
       @worker_notify_wakeup = nil
+      @worker_notify_scope = :supervisor
+      @streams_listen_scope = :master
       @worker_notify_host = nil
       @worker_notify_port = nil
       @worker_notify_database_url = nil
@@ -623,6 +633,56 @@ module Pgbus
       @doctor_on_boot = coerced
     end
 
+    # Where the streams LISTEN connection lives (issue #382):
+    #   :master (default) — ONE shared listener in the preforking web master
+    #     (MasterHub); workers connect lazily over a Unix socket and fall back
+    #     to a per-worker listener whenever the hub is absent or dies.
+    #   :process — one listener per web process: the pre-0.13 behavior, and
+    #     the automatic behavior on single-mode / non-preforking servers.
+    attr_reader :streams_listen_scope
+
+    VALID_STREAMS_LISTEN_SCOPES = %i[master process].freeze
+
+    def streams_listen_scope=(scope)
+      coerced = case scope
+                when Symbol then scope
+                when String then scope.to_sym
+                else
+                  raise Pgbus::ConfigurationError,
+                        "Invalid streams_listen_scope type: #{scope.class}. " \
+                        "Must be :master (one shared LISTEN connection per web host) or :process (one per worker)"
+                end
+      unless VALID_STREAMS_LISTEN_SCOPES.include?(coerced)
+        raise Pgbus::ConfigurationError,
+              "Invalid streams_listen_scope: #{coerced.inspect}. " \
+              "Must be :master (one shared LISTEN connection per web host) or :process (one per worker)"
+      end
+
+      @streams_listen_scope = coerced
+    end
+
+    VALID_WORKER_NOTIFY_SCOPES = %i[supervisor fork].freeze
+
+    # Validated at assignment time like the other enum options. A String is
+    # coerced so YAML-ish configs work.
+    def worker_notify_scope=(scope)
+      coerced = case scope
+                when Symbol then scope
+                when String then scope.to_sym
+                else
+                  raise Pgbus::ConfigurationError,
+                        "Invalid worker_notify_scope type: #{scope.class}. " \
+                        "Must be :supervisor (one shared LISTEN connection per host) or :fork (one per fork)"
+                end
+      unless VALID_WORKER_NOTIFY_SCOPES.include?(coerced)
+        raise Pgbus::ConfigurationError,
+              "Invalid worker_notify_scope: #{coerced.inspect}. " \
+              "Must be :supervisor (one shared LISTEN connection per host) or :fork (one per fork)"
+      end
+
+      @worker_notify_scope = coerced
+    end
+
     def validate!
       if pool_size && !(pool_size.is_a?(Numeric) && pool_size.positive?)
         raise Pgbus::ConfigurationError, "pool_size must be a positive number or nil (auto-tune)"

data/lib/pgbus/dedicated_connection.rb

@@ -16,10 +16,17 @@ module Pgbus
   module DedicatedConnection
     module_function
 
+    # Stable census tag for every dedicated LISTEN connection, so operators can
+    # count them: SELECT count(*) FROM pg_stat_activity WHERE application_name
+    # = 'pgbus-listen' (issue #381 connection budget). Applied as
+    # fallback_application_name so an explicit application_name in the URL /
+    # hash — or PGAPPNAME in the environment — always wins.
+    APP_NAME = "pgbus-listen"
+
     def connect(opts)
       require "pg" unless defined?(::PG::Connection)
       case opts
-      when String then ::PG.connect(opts)
+      when String then ::PG.connect(with_app_name(opts))
       when Hash then connect_from_hash(opts)
       else
         raise Pgbus::ConfigurationError,
@@ -28,9 +35,23 @@ module Pgbus
       end
     end
 
+    # Append the census tag to a conninfo String — URL query-param style for
+    # postgres:// URLs, space-separated keyword style otherwise. A string that
+    # already mentions application_name (either keyword) is left untouched.
+    def with_app_name(conninfo)
+      return conninfo if conninfo.include?("application_name")
+
+      if conninfo.include?("://")
+        separator = conninfo.include?("?") ? "&" : "?"
+        "#{conninfo}#{separator}fallback_application_name=#{APP_NAME}"
+      else
+        "#{conninfo} fallback_application_name=#{APP_NAME}".strip
+      end
+    end
+
     def connect_from_hash(opts)
       variables = opts[:variables]
-      conn = ::PG.connect(**opts.except(:variables))
+      conn = ::PG.connect(**with_app_name_hash(opts.except(:variables)))
       begin
         variables&.each { |name, value| conn.exec("SET #{name} = '#{value}'") }
       rescue StandardError
@@ -44,6 +65,12 @@ module Pgbus
       conn
     end
 
+    def with_app_name_hash(opts)
+      return opts if opts.key?(:application_name) || opts.key?(:fallback_application_name)
+
+      opts.merge(fallback_application_name: APP_NAME)
+    end
+
     def close_quietly(conn)
       conn.close
     rescue StandardError

data/lib/pgbus/doctor.rb

@@ -5,7 +5,7 @@ require "pgbus/mcp/health_analyzer"
 
 module Pgbus
   # Preflight diagnostics for a pgbus deployment — the single command that
-  # answers "is this environment healthy enough to run?". Runs ten checks and
+  # answers "is this environment healthy enough to run?". Runs eleven checks and
   # returns a machine-readable result plus a human report, so `pgbus doctor`
   # and `rake pgbus:doctor` can gate a deploy or CI run (exit 0 on success,
   # 1 on any failure).
@@ -40,7 +40,8 @@ module Pgbus
       "GlobalID allowlist" => :check_allowed_global_id_models,
       "Broadcast queue" => :check_broadcast_queue,
       "Primary affinity" => :check_primary,
-      "Dedicated connections" => :check_dedicated_connections
+      "Dedicated connections" => :check_dedicated_connections,
+      "Connection budget" => :check_connection_budget
     }.freeze
 
     # Process liveness reads the pgbus_processes table (via HealthAnalyzer), so
@@ -366,6 +367,50 @@ module Pgbus
       Check.new(name: "Dedicated connections", status: :fail, detail: "#{e.class}: #{e.message}")
     end
 
+    # How many direct LISTEN connections this config pins at steady state
+    # (issue #381) — informational (always :ok) so operators can do capacity
+    # math on the pooler's direct-connection budget from the doctor output.
+    # Under :supervisor scope the whole host shares 1; under :fork it is one
+    # 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
+      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
+        else
+          capsules + 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)",
+        count: count, plural: count == 1 ? "" : "s", scope: @config.worker_notify_scope,
+        capsules: capsules, cap_plural: capsules == 1 ? "" : "s",
+        consumers: consumers, con_plural: consumers == 1 ? "" : "s",
+        share: count == 1 && @config.worker_notify_scope == :supervisor ? " share it" : ""
+      )
+      detail += streams_budget_clause if @config.streams_enabled
+      Check.new(name: "Connection budget", status: :ok, detail: detail)
+    rescue StandardError => e
+      Check.new(name: "Connection budget", status: :warn, detail: "#{e.class}: #{e.message}")
+    end
+
+    # Streams add their own LISTEN footprint on web hosts: one per host with
+    # the master hub (#382, the default — workers fall back per-worker only
+    # during a hub outage), one per web process under :process scope.
+    def streams_budget_clause
+      if @config.streams_listen_scope == :master
+        " + 1 per web host (streams master hub; per-worker fallback during a hub outage costs 1 per web process)"
+      else
+        " + 1 per web-server process (streams)"
+      end
+    end
+
     # Open one dedicated connection the way the runtime does, verify it
     # answers, close it. Returns nil on success, "label: error" on failure.
     def probe_dedicated_connection(label, opts)

data/lib/pgbus/event_bus/registry.rb

@@ -80,6 +80,28 @@ module Pgbus
         @mutex.synchronize { @subscribers.clear }
       end
 
+      # Logical queue names a consumer subscribed to +topics+ reads from — the
+      # derivation Consumer#setup_subscriptions uses, exposed here so the
+      # supervisor-owned NotifyHub (issue #381) computes the same LISTEN set
+      # the consumer forks actually read. The overlap check is deliberately
+      # coarse: any topic filter ending in "#" claims every subscriber (read
+      # more queues rather than risk an uncovered subscriber).
+      def queue_names_for_topics(topics)
+        subscribers = @mutex.synchronize { @subscribers.dup }
+        subscribers
+          .select { |s| topics.any? { |t| pattern_overlaps?(t, s.pattern) } }
+          .map(&:queue_name)
+          .uniq
+      end
+
+      # Preserved verbatim from Consumer#pattern_overlaps?: true when either
+      # side is a superset of the other by the cheap prefix/suffix rules.
+      def pattern_overlaps?(topic_filter, subscription_pattern)
+        topic_filter == subscription_pattern ||
+          topic_filter.end_with?("#") ||
+          subscription_pattern.start_with?(topic_filter.delete_suffix(".#"))
+      end
+
       private
 
       # Rake task-name prefixes during which pgbus must NOT open a PGMQ

data/lib/pgbus/process/consumer.rb

@@ -14,6 +14,9 @@ module Pgbus
       # notify_retry_at is writable so a test can re-arm the backoff window
       # between successive ensure_notify_listener calls.
       attr_accessor :notify_listener, :notify_retry_at
+      # Supervisor-mediated wake source (issue #381): non-nil iff the
+      # supervisor forked us with a wake pipe. Readable as a test seam.
+      attr_reader :wake_pipe
       # stat_buffer is writable so a test can swap in a buffer double after
       # construction and assert graceful_shutdown / check_recycle / shutdown flush
       # it (mirrors Worker#stat_buffer).
@@ -57,7 +60,7 @@ module Pgbus
                      queue_names: nil, liveness_pipe: nil, stat_buffer: :default,
                      notify_listener: nil, notify_retry_at: 0.0,
                      notify_retry_backoff: NOTIFY_RETRY_BASE_SECONDS,
-                     started_at_monotonic: nil)
+                     started_at_monotonic: nil, wake_pipe: nil)
         @topics = Array(topics)
         @threads = threads
         @config = config
@@ -96,6 +99,9 @@ module Pgbus
         # supervisor forked us with one. Written from stamp_loop_tick so the
         # watchdog can detect a wedged consumer even when the database is down.
         @liveness_pipe = liveness_pipe
+        # Supervisor wake pipe (read end): when present the fork owns NO
+        # LISTEN connection — wakes and hub health arrive as bytes (issue #381).
+        @wake_pipe = wake_pipe ? WakePipe.new(wake_pipe, wake_signal: @wake_signal) : nil
       end
 
       # The last wall-clock loop-tick stamp (Time.now.to_f) fed to the
@@ -110,7 +116,7 @@ module Pgbus
         setup_signals
         start_heartbeat
         setup_subscriptions
-        start_notify_listener
+        start_wake_source
         Pgbus.logger.info do
           "[Pgbus] Consumer started: topics=#{topics.join(",")} threads=#{threads} " \
             "notify_wakeup=#{notify_wakeup?} pid=#{::Process.pid}"
@@ -150,10 +156,13 @@ module Pgbus
       private
 
       def setup_subscriptions
-        matching = @registry.subscribers.select do |s|
-          topics.any? { |t| pattern_overlaps?(t, s.pattern) }
-        end
-        @queue_names = matching.map(&:queue_name).uniq
+        # An injected queue_names: seed (test seam — the ctor documents nil as
+        # "derive from the registry") survives #run. Derivation is shared with
+        # the supervisor-owned NotifyHub (issue #381) so the LISTEN union
+        # covers exactly the queues this fork reads.
+        return unless @queue_names.nil?
+
+        @queue_names = @registry.queue_names_for_topics(topics)
       end
 
       def consume
@@ -273,13 +282,6 @@ module Pgbus
         end
       end
 
-      def pattern_overlaps?(topic_filter, subscription_pattern)
-        # Simple check: if either is a subset of the other
-        topic_filter == subscription_pattern ||
-          topic_filter.end_with?("#") ||
-          subscription_pattern.start_with?(topic_filter.delete_suffix(".#"))
-      end
-
       # Signal the loop to exit cleanly once a recycle limit is hit. The clean
       # exit gets an immediate supervisor restart (supervisor.rb:305-307), so a
       # fresh fork replaces this one before its memory grows unbounded — the
@@ -351,21 +353,49 @@ module Pgbus
       end
 
       def wake_timeout
-        # A dead listener (running? false) will never wake the loop, so treat it
-        # as absent and keep polling at the short interval until
-        # ensure_notify_listener restarts it. Only a live listener earns the
-        # long NOTIFY-mode ceiling.
-        return config.polling_interval unless notify_wakeup? && @notify_listener&.running?
+        # A dead listener (running? false) will never wake the loop, so treat
+        # it as absent and keep polling at the short interval until
+        # ensure_notify_listener restarts it. A live-but-deaf listener
+        # (delivering? false) is the same story (issue #332 — parity with
+        # Worker#wake_timeout). Under :supervisor scope the hub's H/P
+        # broadcasts (via WakePipe) carry the same signal. Only a live,
+        # delivering wake source earns the long NOTIFY-mode ceiling.
+        return config.polling_interval unless notify_wakeup? && wake_source_delivering?
 
         [config.polling_interval, NOTIFY_FALLBACK_POLL_SECONDS].max
       end
 
+      def wake_source_delivering?
+        return @wake_pipe.delivering? if @wake_pipe
+
+        @notify_listener&.running? && @notify_listener.delivering?
+      end
+
+      # :supervisor scope: the fork opens NO LISTEN connection; the WakePipe
+      # watcher is the wake source, and a missing pipe (hub failed to start)
+      # means plain polling — never a local listener (see Worker's twin).
+      # :fork scope: the fork-local NotifyListener.
+      def start_wake_source
+        return @wake_pipe.start if @wake_pipe
+
+        start_notify_listener if local_listener_scope?
+      end
+
+      def local_listener_scope?
+        config.worker_notify_scope == :fork
+      end
+
+      def stop_wake_source
+        @wake_pipe&.stop
+        @notify_listener&.stop
+      end
+
       def start_notify_listener
         return unless notify_wakeup?
 
         @notify_listener = NotifyListener.new(
           physical_queues: physical_queue_names,
-          on_wake: -> { @wake_signal.notify! },
+          on_wake: ->(_channel) { @wake_signal.notify! },
           connection_options: config.worker_notify_connection_options,
           health_check_ms: (config.polling_interval * 1000).to_i.clamp(250, 5_000),
           logger: Pgbus.logger
@@ -382,6 +412,10 @@ module Pgbus
       # a persistent outage retries on 5s→…→300s intervals, not every tick
       # (mirrors Worker#ensure_notify_listener).
       def ensure_notify_listener
+        # Supervisor scope: self-healing is the hub's job (once per host);
+        # a pipe-less fork under that scope stays on plain polling.
+        return if @wake_pipe
+        return unless local_listener_scope?
         return unless notify_wakeup?
         return if @notify_listener&.running?
         return if monotonic_now < @notify_retry_at
@@ -409,9 +443,10 @@ module Pgbus
         @notify_listener = nil
       end
 
+      # Through config.queue_name so normalized subscriber queue names LISTEN
+      # on the channel their table actually notifies (see Worker's twin).
       def physical_queue_names
-        prefix = "#{config.queue_prefix}_"
-        @queue_names.map { |q| "#{prefix}#{q}" }
+        @queue_names.map { |q| config.queue_name(q) }
       end
 
       def start_heartbeat
@@ -443,7 +478,7 @@ module Pgbus
       end
 
       def shutdown
-        @notify_listener&.stop
+        stop_wake_source
         @pool.shutdown
         @pool.wait_for_termination(30)
         @stat_buffer&.stop