pgbus 0.12.3 → 0.13.0

data/lib/pgbus/process/supervisor.rb

@@ -21,23 +21,29 @@ module Pgbus
       RESTART_BACKOFF_MAX = 60
 
       attr_reader :config
+      # The host-level shared LISTEN hub (issue #381). nil under :fork scope,
+      # when notify wakeups are off entirely, or when no worker/consumer role
+      # is enabled. Readable as a test seam.
+      attr_reader :notify_hub
       # forks is readable everywhere; the writer exists only so tests can seed a
       # known set of children before exercising the reap/watchdog paths (in
       # production forks is populated by fork_* as children spawn).
       attr_accessor :forks
 
-      # The child-fork bookkeeping (`forks`, `pending_restarts`) and the
-      # `shutting_down` flag accept injected seeds so tests can drive the
-      # monitor/reap loops from a known state without poking private ivars. All
-      # default to the empty/false values production always starts from.
+      # The child-fork bookkeeping (`forks`, `pending_restarts`), the
+      # `shutting_down` flag, and `notify_hub` accept injected seeds so tests
+      # can drive the monitor/reap loops from a known state without poking
+      # private ivars. All default to the empty/false values production always
+      # starts from.
       def initialize(config: Pgbus.configuration, forks: {}, shutting_down: false,
-                     pending_restarts: [], last_watchdog_at: nil)
+                     pending_restarts: [], last_watchdog_at: nil, notify_hub: nil)
         @config = config
         @forks = forks
         @shutting_down = shutting_down
         @last_watchdog_at = last_watchdog_at || monotonic_now
         @pending_restarts = pending_restarts
         @crash_counts = Hash.new(0)
+        @notify_hub = notify_hub
       end
 
       def shutting_down?
@@ -84,6 +90,12 @@ module Pgbus
         # genuinely-fatal finding; :report only logs. Off by default.
         run_doctor_preflight unless config.doctor_on_boot.nil?
 
+        # Host-level shared LISTEN (issue #381): under :supervisor scope, ONE
+        # NotifyListener lives here and forks are woken over pipes — started
+        # before any child forks so every fork_worker/fork_consumer can hand
+        # its child a wake pipe.
+        start_notify_hub
+
         boot_processes
         monitor_loop
       ensure
@@ -122,7 +134,9 @@ module Pgbus
           "[Pgbus] boot: pgmq_schema_mode=#{config.pgmq_schema_mode} pgmq_version=#{installed_pgmq_version}"
         end
         Pgbus.logger.info do
-          "[Pgbus] boot: listen_notify=#{config.listen_notify} worker_notify_wakeup=#{config.worker_notify_wakeup?}"
+          "[Pgbus] boot: listen_notify=#{config.listen_notify} " \
+            "worker_notify_wakeup=#{config.worker_notify_wakeup?} " \
+            "worker_notify_scope=#{config.worker_notify_scope}"
         end
         Pgbus.logger.info { "[Pgbus] boot: roles=#{enabled_roles.join(",")}" }
         log_capsule_banner
@@ -250,17 +264,18 @@ module Pgbus
         # iteration, the parent drains the reader in monitor_loop. This lets
         # the watchdog detect a wedged worker without the database.
         liveness_reader, liveness_writer = IO.pipe
+        # Wake channel, opposite direction (issue #381): the NotifyHub writes
+        # W/H/P bytes, the child's WakePipe watcher reads them. Only under
+        # :supervisor scope (hub present).
+        wake_reader, wake_writer = IO.pipe if @notify_hub
 
         pid = fork do
-          # Child owns the writer end. A fork copies the whole parent FD
-          # table, so this child also inherits every earlier sibling's
-          # liveness reader (they live in @forks). Close them — otherwise each
-          # new worker accumulates N-1 stale reader FDs. (Sibling *writers*
-          # are never inherited: the parent closes each writer below before
-          # forking the next worker, so a dead sibling's pipe still reaches
-          # EOF correctly.) Finally close this fork's own reader copy.
-          close_inherited_liveness_readers
+          # Child owns the liveness writer + wake reader; close this fork's
+          # own copies of the parent-side ends. Sibling pipe ends and the
+          # hub's LISTEN socket are released in setup_child_process, which
+          # every child type runs.
           liveness_reader.close
+          wake_writer&.close
           restore_signals
           setup_child_process
           load_rails_app
@@ -269,7 +284,7 @@ module Pgbus
             queues: queues, threads: threads, config: config,
             single_active_consumer: single_active, consumer_priority: priority,
             execution_mode: exec_mode, group_mode: grp_mode,
-            liveness_pipe: liveness_writer
+            liveness_pipe: liveness_writer, wake_pipe: wake_reader
           )
           worker.run
         end
@@ -277,24 +292,50 @@ module Pgbus
         unless pid
           close_pipe(liveness_reader)
           close_pipe(liveness_writer)
+          close_pipe(wake_reader)
+          close_pipe(wake_writer)
           Pgbus.logger.error { "[Pgbus] Failed to fork worker for queues=#{queues.join(",")}" }
           return
         end
 
-        # Parent keeps the reader, discards its writer copy so the pipe reaches
-        # EOF once the (sole remaining) child writer closes.
+        # Parent keeps the liveness reader + wake writer, discards its copies
+        # of the child-side ends so each pipe reaches EOF once its sole owner
+        # closes.
         close_pipe(liveness_writer)
+        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,
-          liveness_reader: liveness_reader, last_pipe_tick_at: monotonic_now, pipe_seen: false
+          liveness_reader: liveness_reader, last_pipe_tick_at: monotonic_now, pipe_seen: false,
+          wake_writer: wake_writer
         }
         Pgbus.logger.info { "[Pgbus] Forked worker pid=#{pid} queues=#{queues.join(",")} mode=#{exec_mode}" }
       rescue Errno::EAGAIN, Errno::ENOMEM => e
         close_pipe(liveness_reader)
         close_pipe(liveness_writer)
+        close_pipe(wake_reader)
+        close_pipe(wake_writer)
         ErrorReporter.report(e, { action: "fork_worker", queues: queues })
       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
+      # needs to be reported upstream). Registration must never abort the fork
+      # bookkeeping that follows it — queue_name can raise on a malformed
+      # name — so on error the fork registers with an empty set and rides its
+      # poll ceiling (symmetric with register_consumer_with_hub).
+      def register_fork_with_hub(pid, wake_writer, queues)
+        return unless @notify_hub && wake_writer
+
+        wildcard = queues.include?("*")
+        physical = queues.reject { |q| q == "*" }.map { |q| config.queue_name(q) }
+        @notify_hub.register_fork(pid: pid, queues: physical, wildcard: wildcard, pipe: wake_writer)
+      rescue StandardError => e
+        ErrorReporter.report(e, { action: "register_fork_with_hub", queues: queues })
+        @notify_hub.register_fork(pid: pid, queues: [], wildcard: false, pipe: wake_writer)
+      end
+
       def fork_dispatcher
         pid = fork do
           restore_signals
@@ -386,7 +427,9 @@ module Pgbus
       end
 
       def fork_consumer(consumer_config, slot: nil)
-        topics = consumer_config[:topics]
+        # Array() so a consumer entry without :topics can't NoMethodError the
+        # supervisor on the topics.join log lines below.
+        topics = Array(consumer_config[:topics])
         threads = consumer_config[:threads] || 3
 
         # OS-level liveness channel: the consumer writes a byte each loop
@@ -394,41 +437,66 @@ module Pgbus
         # watchdog detect a wedged consumer without the database (issue #274),
         # exactly as fork_worker does for workers.
         liveness_reader, liveness_writer = IO.pipe
+        # Wake channel from the NotifyHub (issue #381), as in fork_worker.
+        wake_reader, wake_writer = IO.pipe if @notify_hub
 
         pid = fork do
-          # Child owns the writer end. Close every earlier sibling's inherited
-          # liveness reader and this fork's own reader copy before becoming a
-          # Consumer (see fork_worker for the full rationale).
-          close_inherited_liveness_readers
+          # Child owns the liveness writer + wake reader; close this fork's
+          # own copies of the parent-side ends (see fork_worker).
           liveness_reader.close
+          wake_writer&.close
           restore_signals
           setup_child_process
           load_rails_app
-          consumer = Consumer.new(topics: topics, threads: threads, config: config, liveness_pipe: liveness_writer)
+          consumer = Consumer.new(topics: topics, threads: threads, config: config,
+                                  liveness_pipe: liveness_writer, wake_pipe: wake_reader)
           consumer.run
         end
 
         unless pid
           close_pipe(liveness_reader)
           close_pipe(liveness_writer)
+          close_pipe(wake_reader)
+          close_pipe(wake_writer)
           Pgbus.logger.error { "[Pgbus] Failed to fork consumer for topics=#{topics.join(",")}" }
           return
         end
 
-        # Parent keeps the reader, discards its writer copy so the pipe reaches
-        # EOF once the (sole remaining) child writer closes.
+        # Parent keeps the liveness reader + wake writer, discards its copies
+        # of the child-side ends.
         close_pipe(liveness_writer)
+        close_pipe(wake_reader)
+        register_consumer_with_hub(pid, wake_writer, topics)
         @forks[pid] = {
           type: :consumer, config: consumer_config, slot: slot, spawned_at: monotonic_now,
-          liveness_reader: liveness_reader, last_pipe_tick_at: monotonic_now, pipe_seen: false
+          liveness_reader: liveness_reader, last_pipe_tick_at: monotonic_now, pipe_seen: false,
+          wake_writer: wake_writer
         }
         Pgbus.logger.info { "[Pgbus] Forked consumer pid=#{pid} topics=#{topics.join(",")}" }
       rescue Errno::EAGAIN, Errno::ENOMEM => e
         close_pipe(liveness_reader)
         close_pipe(liveness_writer)
+        close_pipe(wake_reader)
+        close_pipe(wake_writer)
         ErrorReporter.report(e, { action: "fork_consumer", topics: topics })
       end
 
+      # A consumer's routing entry mirrors Consumer#setup_subscriptions: the
+      # registry derives the queue set from the topic list. Registry lookups
+      # never abort a fork — on error the fork registers with an empty set and
+      # rides its poll ceiling until the next supervisor restart.
+      def register_consumer_with_hub(pid, wake_writer, topics)
+        return unless @notify_hub && wake_writer
+
+        physical = EventBus::Registry.instance
+                                     .queue_names_for_topics(Array(topics))
+                                     .map { |q| config.queue_name(q) }
+        @notify_hub.register_fork(pid: pid, queues: physical, wildcard: false, pipe: wake_writer)
+      rescue StandardError => e
+        ErrorReporter.report(e, { action: "register_consumer_with_hub", topics: topics })
+        @notify_hub.register_fork(pid: pid, queues: [], wildcard: false, pipe: wake_writer)
+      end
+
       def boot_outbox_poller
         return unless config.outbox_enabled
 
@@ -465,6 +533,9 @@ module Pgbus
           unless @shutting_down
             process_pending_restarts
             check_stalled_workers
+            # One hub beat per monitor pass: listener self-heal, LISTEN union
+            # refresh, and fork status broadcast (issue #381).
+            @notify_hub&.tick
           end
           interruptible_sleep(FORK_WAIT)
         end
@@ -480,8 +551,11 @@ module Pgbus
 
           # Close the liveness reader as the fork leaves @forks so a crash-loop
           # (restart deferred up to RESTART_BACKOFF_MAX) can't leak an FD per
-          # crash. Scrub the key so the closed IO never rides into a restart.
+          # crash. Scrub the keys so a closed IO never rides into a restart.
+          # The wake writer is closed by the hub's deregister (same IO object).
           close_pipe(info.delete(:liveness_reader))
+          info.delete(:wake_writer)
+          @notify_hub&.deregister_fork(pid)
 
           if @shutting_down
             Pgbus.logger.info { "[Pgbus] Child #{info[:type]} pid=#{pid} exited (status=#{status.exitstatus})" }
@@ -655,6 +729,13 @@ module Pgbus
       end
 
       def setup_child_process
+        # Every child type (worker, consumer, dispatcher, scheduler, outbox
+        # poller) releases its copies of the parent's per-fork resources —
+        # a dispatcher child holding a sibling worker's wake WRITER would
+        # keep that sibling's pipe from ever reaching EOF after the
+        # supervisor dies, pinning the sibling to the 15s NOTIFY ceiling
+        # with no wake source (issue #381 review).
+        close_inherited_parent_resources
         # Reset the PGMQ client so this forked process gets a fresh
         # PG::Connection instead of inheriting the parent's (which is
         # in undefined state post-fork and not thread-safe to share).
@@ -758,11 +839,40 @@ module Pgbus
         nil
       end
 
-      # Close every sibling liveness reader this fork inherited from the
-      # parent's FD table. Called only inside a just-forked child, before it
-      # becomes a Worker, so the worker never holds its siblings' pipe ends.
-      def close_inherited_liveness_readers
-        @forks.each_value { |info| close_pipe(info[:liveness_reader]) }
+      # Called only inside a just-forked child: close every sibling pipe end
+      # inherited from the parent's FD table (liveness readers AND wake
+      # writers), and release the child's copy of the NotifyHub's LISTEN
+      # socket without a libpq Terminate (PQfinish would kill the PARENT's
+      # session over the shared socket — see
+      # NotifyListener#close_inherited_socket!).
+      def close_inherited_parent_resources
+        @forks.each_value do |info|
+          close_pipe(info[:liveness_reader])
+          close_pipe(info[:wake_writer])
+        end
+        @notify_hub&.close_inherited!
+        @notify_hub = nil
+      end
+
+      # Build the host-level shared LISTEN hub (issue #381). Only under
+      # :supervisor scope, with notify wakeups on, and with at least one role
+      # that reads queues. A hub that fails to start degrades to no hub: forks
+      # get no wake pipe and fall back to fast polling, exactly like a failed
+      # per-fork listener under :fork scope.
+      def start_notify_hub
+        return unless config.worker_notify_wakeup?
+        return unless config.worker_notify_scope == :supervisor
+        return unless config.role_enabled?(:workers) || config.role_enabled?(:consumers)
+
+        hub = NotifyHub.new(config: config)
+        hub.start
+        @notify_hub = hub
+      rescue StandardError => e
+        @notify_hub = nil
+        ErrorReporter.report(e, { action: "start_notify_hub" })
+        Pgbus.logger.error do
+          "[Pgbus] NotifyHub failed to start — forks fall back to polling: #{e.class}: #{e.message}"
+        end
       end
 
       def shutdown
@@ -778,9 +888,11 @@ module Pgbus
         signal_children("KILL") unless @forks.empty?
 
         # Close any liveness readers still open on un-reaped children so the
-        # supervisor never leaks FDs across a restart of itself.
+        # supervisor never leaks FDs across a restart of itself. (Wake writers
+        # are closed by the hub's stop below.)
         @forks.each_value { |info| close_pipe(info[:liveness_reader]) }
 
+        @notify_hub&.stop
         @health_server&.stop
         @heartbeat&.stop
         restore_signals

data/lib/pgbus/process/wake_pipe.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Process
+    # Fork-side receiver for supervisor-mediated wake-ups (issue #381,
+    # worker_notify_scope: :supervisor). The supervisor's NotifyHub holds the
+    # write end of a per-fork pipe; this class owns the inherited read end and
+    # a single watcher thread that translates the byte protocol into the
+    # fork's existing primitives:
+    #
+    #   W — a NOTIFY arrived for a queue this fork reads → wake_signal.notify!
+    #   H — the shared listener is healthy (connected + delivering) → the
+    #       fork may sleep up to the NOTIFY poll ceiling
+    #   P — the shared listener is degraded (dead thread, mid-reconnect,
+    #       pooler-deaf) → the fork falls back to fast polling
+    #
+    # Status starts optimistic (mirrors NotifyListener's @delivering default)
+    # so a just-forked worker isn't pinned to fast polling before the hub's
+    # first broadcast. EOF on the pipe means the supervisor is gone: mark
+    # not-delivering and let the fork run on plain polling.
+    #
+    # A nil reader (scope :fork, or the supervisor never armed the pipe)
+    # yields an inert instance: start is a no-op and delivering? is false, so
+    # wake_timeout math treats it exactly like an absent listener.
+    class WakePipe
+      WAKE = "W"
+      HEALTHY = "H"
+      DEGRADED = "P"
+
+      def initialize(reader, wake_signal:, logger: Pgbus.logger)
+        @reader = reader
+        @wake_signal = wake_signal
+        @logger = logger
+        @state_mutex = Mutex.new
+        @running = false
+        @thread = nil
+        @delivering = !reader.nil?
+      end
+
+      def delivering?
+        @state_mutex.synchronize { @delivering }
+      end
+
+      def running?
+        @state_mutex.synchronize { @running }
+      end
+
+      def start
+        return self if @reader.nil?
+
+        @state_mutex.synchronize do
+          return self if @running
+
+          @running = true
+        end
+        @thread = Thread.new { run_loop }
+        self
+      end
+
+      def stop
+        @state_mutex.synchronize do
+          return self unless @running
+
+          @running = false
+        end
+        # Closing the pipe FD interrupts the watcher's blocking readpartial —
+        # Ruby raises IOError in the blocked thread at the interpreter level.
+        # (Safe for a plain IO, unlike PG::Connection#close, which is PQfinish
+        # under a concurrent libpq call — issue #375. That constraint is about
+        # libpq, not IO.)
+        close_reader_quietly
+        @thread&.join(2)
+        @thread = nil
+        self
+      end
+
+      private
+
+      def run_loop
+        loop do
+          break unless running?
+
+          handle_bytes(@reader.readpartial(4096))
+        end
+      rescue EOFError
+        # Supervisor exited: no more wakes will ever arrive on this pipe.
+        mark_not_delivering("supervisor wake pipe reached EOF — falling back to polling")
+      rescue IOError, Errno::EBADF
+        # Reader closed under us. Expected during #stop (running? already
+        # false); anything else degrades to polling like EOF.
+        mark_not_delivering("supervisor wake pipe closed — falling back to polling") if running?
+      rescue StandardError => e
+        mark_not_delivering("supervisor wake pipe failed (#{e.class}: #{e.message}) — falling back to polling")
+      ensure
+        @state_mutex.synchronize { @running = false }
+      end
+
+      # One coalesced read may carry several bytes. Status transitions apply
+      # in order; any number of W bytes collapses into one notify! (WakeSignal
+      # coalesces concurrent notifies anyway).
+      def handle_bytes(data)
+        wake = false
+        data.each_char do |byte|
+          case byte
+          when WAKE then wake = true
+          when HEALTHY then update_delivering(true)
+          when DEGRADED then update_delivering(false)
+          end
+        end
+        @wake_signal.notify! if wake
+      end
+
+      def update_delivering(value)
+        @state_mutex.synchronize { @delivering = value }
+      end
+
+      def mark_not_delivering(message)
+        update_delivering(false)
+        @logger.warn { "[Pgbus::WakePipe] #{message}" }
+      end
+
+      def close_reader_quietly
+        @reader.close if @reader && !@reader.closed?
+      rescue IOError, Errno::EBADF
+        nil
+      end
+    end
+  end
+end

data/lib/pgbus/process/wildcard_queue_resolver.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Process
+    # Resolves a wildcard ("*") queue list to the concrete logical queue names
+    # a job worker may adopt: every pgmq.meta queue minus dead-letter queues,
+    # stream queues (issue #309/#366 — a job worker adopting one would claim
+    # durable broadcasts and DLQ-move them out of replay history), and
+    # event-subscriber queues (issue #333 — event payloads, not ActiveJob
+    # jobs), with the configured prefix stripped.
+    #
+    # Shared by Worker#resolve_wildcard_queues (per-fork adoption) and the
+    # supervisor-owned NotifyHub (issue #381 — the LISTEN union for wildcard
+    # capsules), so both sides of the wake path agree on what "*" means.
+    module WildcardQueueResolver
+      module_function
+
+      def resolve(config: Pgbus.configuration)
+        prefix = "#{config.queue_prefix}_"
+
+        # Reset first so a stream created since the last resolve is excluded.
+        Pgbus::StreamQueue.reset_cache!
+        stream_names = Pgbus::StreamQueue.known_names
+        event_names = Pgbus::EventBus::Registry.instance.event_queue_names
+
+        conn = config.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
+        conn.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
+            .reject { |q| q.end_with?(Pgbus::DEAD_LETTER_SUFFIX) }
+            .reject { |q| stream_names.include?(q) }
+            .reject { |q| event_names.include?(q) }
+            .map { |q| q.delete_prefix(prefix) }
+      end
+    end
+  end
+end

data/lib/pgbus/process/worker.rb

@@ -19,6 +19,11 @@ module Pgbus
       # between calls, and simulate start_notify_listener assigning the listener
       # from inside a stub (production mutates all three in the run loop).
       attr_accessor :notify_listener, :notify_retry_at, :notify_retry_backoff
+      # Supervisor-mediated wake source (issue #381, worker_notify_scope:
+      # :supervisor). Non-nil iff the supervisor forked us with a wake pipe;
+      # its presence switches the whole notify lifecycle from a fork-local
+      # NotifyListener to the shared hub. Readable as a test seam.
+      attr_reader :wake_pipe
 
       # The collaborators below (rate_counter, wake_signal, stat_buffer) and the
       # recycle clock (started_at_monotonic) accept injected seeds so tests can
@@ -30,7 +35,7 @@ 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)
+                     started_at_monotonic: nil, wake_pipe: nil)
         @queues = Array(queues)
         @initial_queues = @queues.dup.freeze
         @wildcard = @queues.include?("*")
@@ -98,6 +103,10 @@ module Pgbus
         # so the watchdog can detect a wedged worker even when the database (and
         # thus the Heartbeat's loop_tick_at) is unavailable.
         @liveness_pipe = liveness_pipe
+        # Supervisor wake pipe (read end, inherited across fork). When present
+        # the fork owns NO LISTEN connection: wakes and listener-health status
+        # arrive as bytes from the supervisor's NotifyHub.
+        @wake_pipe = wake_pipe ? WakePipe.new(wake_pipe, wake_signal: @wake_signal) : nil
       end
 
       def stats
@@ -150,7 +159,7 @@ module Pgbus
         setup_signals
         start_heartbeat
         resolve_wildcard_queues
-        start_notify_listener
+        start_wake_source
         @lifecycle.transition_to!(:running)
         Pgbus.logger.info do
           "[Pgbus] Worker started: queues=#{queues.join(",")} threads=#{threads} " \
@@ -404,34 +413,10 @@ module Pgbus
       def resolve_wildcard_queues
         return unless @wildcard
 
-        dlq_suffix = Pgbus::DEAD_LETTER_SUFFIX
-        prefix = "#{config.queue_prefix}_"
-
-        # Stream queues share the job namespace (pgbus_<name>) but must never
-        # be adopted by a wildcard worker: a worker would claim durable
-        # broadcasts, fail to deserialize them, and DLQ-move them out of the
-        # stream's replay history. known_names includes fingerprint-matched
-        # dormant pre-registry streams (issue #366) so they are excluded even
-        # before backfill. Reset first so a stream created since the last
-        # resolve is excluded.
-        Pgbus::StreamQueue.reset_cache!
-        stream_names = Pgbus::StreamQueue.known_names
-
-        # Event-bus subscriber queues also share the job namespace (pgbus_<handler>)
-        # but carry event payloads, not ActiveJob jobs. A wildcard worker that
-        # adopts one hands the event to the executor, which fails to deserialize
-        # it and DLQ-moves it out of the consumer's reach — so an app running the
-        # event bus had to hand-maintain an explicit queue list. Exclude them,
-        # like stream queues (issue #333).
-        event_names = Pgbus::EventBus::Registry.instance.event_queue_names
-
-        conn = Pgbus.configuration.connects_to ? Pgbus::BusRecord.connection : ActiveRecord::Base.connection
-        all_queues = conn.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
-        resolved = all_queues
-                   .reject { |q| q.end_with?(dlq_suffix) }
-                   .reject { |q| stream_names.include?(q) }
-                   .reject { |q| event_names.include?(q) }
-                   .map { |q| q.delete_prefix(prefix) }
+        # Exclusion rationale (streams, event queues, DLQs) lives with the
+        # shared resolver — the NotifyHub uses the same one, so the LISTEN
+        # union and the fork's adopted set can't drift (issue #381).
+        resolved = WildcardQueueResolver.resolve(config: config)
 
         if resolved.empty?
           Pgbus.logger.warn { "[Pgbus] Wildcard queue '*' resolved to no queues — falling back to default" }
@@ -627,6 +612,10 @@ module Pgbus
       end
 
       def listener_delivering?
+        # Supervisor scope: the hub's H/P broadcasts (via WakePipe) stand in
+        # for the local listener's health — same fast-poll fallback rules.
+        return @wake_pipe.delivering? if @wake_pipe
+
         @notify_listener&.running? && @notify_listener.delivering?
       end
 
@@ -642,12 +631,35 @@ module Pgbus
         config.polling_interval
       end
 
+      # :supervisor scope: the fork opens NO LISTEN connection; the WakePipe
+      # watcher is the wake source. A missing pipe under that scope means the
+      # hub failed to start — plain polling, NEVER a local listener, or a hub
+      # outage would balloon the host back to one direct connection per fork
+      # (the exact budget the scope exists to protect). :fork scope: the
+      # fork-local NotifyListener, exactly as before.
+      def start_wake_source
+        return @wake_pipe.start if @wake_pipe
+
+        start_notify_listener if local_listener_scope?
+      end
+
+      # Local NotifyListener lifecycle (start + self-heal) is allowed only
+      # under :fork scope.
+      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
@@ -666,6 +678,12 @@ module Pgbus
       # its queue subscription reconciled (wildcard workers) and the backoff
       # reset; a still-failing restart doubles the backoff up to the cap.
       def ensure_notify_listener
+        # Supervisor scope: listener self-healing is the hub's job (it runs
+        # once per host in the supervisor's monitor tick), and a pipe-less
+        # fork under that scope must stay on plain polling — self-healing a
+        # listener it was never allowed to start would leak a connection.
+        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
@@ -706,13 +724,18 @@ module Pgbus
         Pgbus.logger.warn { "[Pgbus] NotifyListener queue sync failed: #{e.class}: #{e.message}" }
       end
 
+      # Through config.queue_name (not raw concatenation) so a logical name
+      # needing normalization (e.g. "orders-handler" → "orders_handler")
+      # yields the SAME physical name the queue table was created with — the
+      # NOTIFY channel derives from the table name, so a raw concat would
+      # LISTEN on a channel that never fires. Keeps the fork-local (:fork
+      # scope) channels identical to the NotifyHub's (issue #381 review).
       def physical_queue_names
-        prefix = "#{config.queue_prefix}_"
-        queues.map { |q| "#{prefix}#{q}" }
+        queues.map { |q| config.queue_name(q) }
       end
 
       def channel_to_physical(channel)
-        channel.delete_prefix(NotifyListener::CHANNEL_PREFIX).delete_suffix(NotifyListener::CHANNEL_SUFFIX)
+        NotifyListener.physical_for(channel)
       end
 
       def start_heartbeat
@@ -767,7 +790,7 @@ module Pgbus
 
       def shutdown
         Pgbus.logger.info { "[Pgbus] Worker draining thread pool..." }
-        @notify_listener&.stop
+        stop_wake_source
         @pool.shutdown
         @pool.wait_for_termination(30)
         @stat_buffer&.stop

data/lib/pgbus/version.rb

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