pgbus 0.12.4 → 0.13.0

data/lib/pgbus/process/notify_hub.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Process
+    # Supervisor-owned LISTEN hub (issue #381, worker_notify_scope:
+    # :supervisor). Owns ONE NotifyListener — one direct PG connection for the
+    # whole host — on the union of every capsule's and consumer's queue
+    # channels, and fans wakes out to worker/consumer forks over per-fork
+    # pipes (see WakePipe for the fork side and the W/H/P byte protocol).
+    #
+    # Union: explicit capsule queues from config.workers, wildcard capsules
+    # via the shared WildcardQueueResolver, consumer queues via
+    # Registry#queue_names_for_topics — each gated by config.role_enabled?.
+    # Refreshed every REFRESH_INTERVAL_SECONDS from the supervisor's monitor
+    # tick so wildcard churn and late registry subscriptions converge; a
+    # transient gap is bounded by the forks' NOTIFY poll ceiling (15s), so
+    # under-listening degrades latency, never liveness.
+    #
+    # Routing: a NOTIFY for queue Q wakes every fork whose registered set
+    # contains Q, plus every wildcard fork. Over-waking costs one empty read;
+    # under-waking is the only failure mode that matters, so wildcard routing
+    # is unconditional.
+    #
+    # Status: healthy? = listener running + connected + delivering. Broadcast
+    # to all pipes on change and every STATUS_REBROADCAST_SECONDS (idempotent
+    # 1-byte writes), so a lost byte or a freshly full pipe can't wedge a fork
+    # in the wrong mode.
+    #
+    # Threading: register/deregister/tick/stop run on the supervisor's main
+    # loop; the wake callback runs on the listener's thread. The fork table is
+    # the only shared state — guarded by @table_mutex. Pipe writes are 1-byte
+    # write_nonblock calls (atomic well under PIPE_BUF) and never block: a
+    # full pipe already guarantees a pending readable byte, so the wake is
+    # skipped, and status repair rides the periodic rebroadcast.
+    class NotifyHub
+      REFRESH_INTERVAL_SECONDS = 30
+      STATUS_REBROADCAST_SECONDS = 5
+      RETRY_BASE_SECONDS = 5
+      RETRY_MAX_SECONDS = 300
+
+      def initialize(config:, listener_factory: nil, clock: nil, logger: Pgbus.logger)
+        @config = config
+        @logger = logger
+        @clock = clock || -> { ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) }
+        @listener_factory = listener_factory || default_listener_factory
+        @table_mutex = Mutex.new
+        @forks = {}
+        @listener = nil
+        @last_status = nil
+        @last_broadcast_at = nil
+        @last_refresh_at = nil
+        @retry_at = 0.0
+        @retry_backoff = RETRY_BASE_SECONDS
+      end
+
+      def start
+        build_listener
+        @last_refresh_at = now
+        self
+      end
+
+      def stop
+        stop_listener_quietly
+        @table_mutex.synchronize do
+          @forks.each_value { |entry| close_quietly(entry[:pipe]) }
+          @forks.clear
+        end
+        self
+      end
+
+      # Register a fork's wake pipe. +queues+ are PHYSICAL queue names (already
+      # prefixed); wildcard forks pass wildcard: true and are woken for every
+      # channel. The fork's current status byte is sent immediately so a
+      # freshly forked worker starts in the right polling mode.
+      def register_fork(pid:, queues:, pipe:, wildcard: false)
+        entry = { pipe: pipe, queues: Set.new(queues), wildcard: wildcard }
+        @table_mutex.synchronize { @forks[pid] = entry }
+        byte = status_byte
+        write_byte(entry, byte)
+        # The registration write is the broadcast baseline: without stamping
+        # it, the next tick would treat @last_status as unknown and re-send
+        # the same byte to every fork immediately.
+        @last_status = byte
+        @last_broadcast_at = now
+        self
+      end
+
+      def deregister_fork(pid)
+        entry = @table_mutex.synchronize { @forks.delete(pid) }
+        close_quietly(entry[:pipe]) if entry
+        self
+      end
+
+      # Called ONLY inside a just-forked child: release the child's copies of
+      # the parent's hub resources — the LISTEN socket fd (without a libpq
+      # Terminate, see NotifyListener#close_inherited_socket!) and the fork
+      # table's pipe write ends. Never touches parent state (fork copied it).
+      def close_inherited!
+        @listener&.close_inherited_socket!
+        @listener = nil
+        @table_mutex.synchronize do
+          @forks.each_value { |entry| close_quietly(entry[:pipe]) }
+          @forks.clear
+        end
+        self
+      end
+
+      # One supervisor monitor-loop beat: self-heal the listener, refresh the
+      # LISTEN union, keep fork status fresh.
+      def tick
+        ensure_listener
+        refresh_union_if_due
+        broadcast_status
+        self
+      end
+
+      def healthy?
+        listener = @listener
+        !!(listener&.running? && listener.connected? && listener.delivering?)
+      end
+
+      private
+
+      attr_reader :config
+
+      def now
+        @clock.call
+      end
+
+      def default_listener_factory
+        lambda do |physical_queues:, on_wake:|
+          NotifyListener.new(
+            physical_queues: physical_queues,
+            on_wake: on_wake,
+            connection_options: config.worker_notify_connection_options,
+            health_check_ms: (config.polling_interval * 1000).to_i.clamp(250, 5_000),
+            logger: @logger
+          )
+        end
+      end
+
+      def build_listener
+        @listener = @listener_factory.call(
+          physical_queues: desired_physical_queues,
+          on_wake: method(:route)
+        )
+        @listener.start
+      rescue StandardError => e
+        @listener = nil
+        @logger.error { "[Pgbus::NotifyHub] listener failed to start: #{e.class}: #{e.message}" }
+      end
+
+      # Mirrors Worker#ensure_notify_listener: restart a dead listener thread
+      # on an exponential backoff so a persistent outage doesn't thrash a
+      # reconnect per supervisor tick.
+      def ensure_listener
+        return if @listener&.running?
+        return if now < @retry_at
+
+        stop_listener_quietly
+        build_listener
+
+        @retry_backoff = if @listener&.running?
+                           RETRY_BASE_SECONDS
+                         else
+                           [@retry_backoff * 2, RETRY_MAX_SECONDS].min
+                         end
+        @retry_at = now + @retry_backoff
+      end
+
+      def stop_listener_quietly
+        @listener&.stop
+      rescue StandardError => e
+        @logger.warn { "[Pgbus::NotifyHub] failed to stop listener: #{e.class}: #{e.message}" }
+      ensure
+        @listener = nil
+      end
+
+      def refresh_union_if_due
+        return unless @listener
+        return if @last_refresh_at && (now - @last_refresh_at) < REFRESH_INTERVAL_SECONDS
+
+        @last_refresh_at = now
+        desired = desired_physical_queues.to_set
+        current = @listener.listening_to.to_set { |channel| channel_to_physical(channel) }
+        (desired - current).each { |q| @listener.add_queue(q) }
+        (current - desired).each { |q| @listener.remove_queue(q) }
+      rescue StandardError => e
+        @logger.warn { "[Pgbus::NotifyHub] union refresh failed: #{e.class}: #{e.message}" }
+      end
+
+      def broadcast_status(status = status_byte)
+        rebroadcast_due = @last_broadcast_at.nil? || (now - @last_broadcast_at) >= STATUS_REBROADCAST_SECONDS
+        return if status == @last_status && !rebroadcast_due
+
+        entries = @table_mutex.synchronize { @forks.values.dup }
+        entries.each { |entry| write_byte(entry, status) }
+        @last_status = status
+        @last_broadcast_at = now
+      end
+
+      def status_byte
+        healthy? ? WakePipe::HEALTHY : WakePipe::DEGRADED
+      end
+
+      # Runs on the LISTENER thread (NotifyListener on_wake callback).
+      def route(channel)
+        physical = channel_to_physical(channel)
+        entries = @table_mutex.synchronize { @forks.values.dup }
+        entries.each do |entry|
+          write_byte(entry, WakePipe::WAKE) if entry[:wildcard] || entry[:queues].include?(physical)
+        end
+      end
+
+      # Never block, never raise: a full pipe already guarantees a pending
+      # readable byte (wake semantics are level-triggered), and a dead pipe's
+      # fork is on its way through reap → deregister_fork.
+      def write_byte(entry, byte)
+        entry[:pipe].write_nonblock(byte)
+      rescue IO::WaitWritable, Errno::EPIPE, IOError, Errno::EBADF
+        nil
+      end
+
+      def desired_physical_queues
+        names = []
+        names.concat(capsule_queue_names) if config.role_enabled?(:workers)
+        names.concat(consumer_queue_names) if config.role_enabled?(:consumers)
+        names.uniq.map { |q| config.queue_name(q) }
+      end
+
+      def capsule_queue_names
+        names = []
+        wildcard = false
+        Array(config.workers).each do |worker_config|
+          queues = worker_config[:queues] || worker_config["queues"] || [config.default_queue]
+          Array(queues).each do |q|
+            q.to_s == "*" ? wildcard = true : names << q.to_s
+          end
+        end
+        names.concat(resolve_wildcard) if wildcard
+        names
+      end
+
+      # A resolver failure (DB blip at boot) degrades to the explicit union;
+      # wildcard queues rejoin on the next successful refresh, and the forks'
+      # poll ceiling keeps them processing meanwhile.
+      def resolve_wildcard
+        WildcardQueueResolver.resolve(config: config)
+      rescue StandardError => e
+        @logger.warn { "[Pgbus::NotifyHub] wildcard resolution failed: #{e.class}: #{e.message}" }
+        []
+      end
+
+      def consumer_queue_names
+        registry = Pgbus::EventBus::Registry.instance
+        Array(config.event_consumers).flat_map do |consumer_config|
+          topics = consumer_config[:topics] || consumer_config["topics"] || []
+          registry.queue_names_for_topics(Array(topics))
+        end
+      end
+
+      def channel_to_physical(channel)
+        NotifyListener.physical_for(channel)
+      end
+
+      def close_quietly(pipe)
+        pipe.close if pipe && !pipe.closed?
+      rescue IOError, Errno::EBADF
+        nil
+      end
+    end
+  end
+end

data/lib/pgbus/process/notify_listener.rb

@@ -42,6 +42,14 @@ module Pgbus
       CHANNEL_PREFIX = "pgmq.q_"
       CHANNEL_SUFFIX = ".INSERT"
 
+      # Inverse of #channel_for: map a NOTIFY channel back to the physical
+      # queue name. Class-level because the channel format is owned here —
+      # NotifyHub (wake routing + union refresh) and Worker (queue-set sync)
+      # both consume it.
+      def self.physical_for(channel)
+        channel.delete_prefix(CHANNEL_PREFIX).delete_suffix(CHANNEL_SUFFIX)
+      end
+
       RECONNECT_BACKOFF_SECONDS = 0.5
 
       # Grace added to one health-check cycle when #stop joins the listener
@@ -70,6 +78,16 @@ module Pgbus
         @state_mutex.synchronize { @listening_to.dup }
       end
 
+      # Whether a live PG connection is currently published. running? stays
+      # true during a reconnect (the thread is alive, looping in reconnect!),
+      # so this is the signal that distinguishes "parked in wait_for_notify"
+      # from "between connections". The supervisor NotifyHub (issue #381)
+      # consults it to broadcast degraded status to forks the moment the
+      # shared connection drops, and healthy again once it is rebuilt.
+      def connected?
+        @state_mutex.synchronize { !@conn.nil? }
+      end
+
       # Whether the start-time self-probe confirmed this connection can actually
       # receive a NOTIFY. False when a transaction-mode pooler or replica
       # silently drops LISTEN: the thread is still alive (running? == true) but
@@ -125,6 +143,30 @@ module Pgbus
         @state_mutex.synchronize { @running }
       end
 
+      # Called ONLY inside a just-forked child (issue #381 hub hygiene): drop
+      # this process's copy of the LISTEN socket fd WITHOUT PQfinish — #close
+      # would send a libpq Terminate over the socket shared with the parent,
+      # killing the parent's LISTEN session. Closing the IO wrapper just
+      # closes the child's fd. The listener thread does not exist in the
+      # child (fork copies only the calling thread), so there is no
+      # concurrent owner and the single-owner rule (#375) does not apply.
+      def close_inherited_socket!
+        conn = @state_mutex.synchronize do
+          c = @conn
+          @conn = nil
+          @running = false
+          c
+        end
+        conn&.socket_io&.close
+      rescue StandardError => e
+        # Best-effort (a lingering fd copy is benign until the parent dies),
+        # but never silent: the child keeps booting either way.
+        @logger.warn do
+          "[Pgbus::NotifyListener] inherited socket cleanup failed: #{e.class}: #{e.message}"
+        end
+        nil
+      end
+
       private
 
       def run_loop
@@ -190,8 +232,11 @@ module Pgbus
         return reconnect! unless conn
 
         timeout_s = @health_check_ms / 1000.0
-        got_notify = conn.wait_for_notify(timeout_s) do |_channel, _pid, _payload|
-          @on_wake.call
+        got_notify = conn.wait_for_notify(timeout_s) do |channel, _pid, _payload|
+          # The channel rides along so a hub caller (issue #381) can route the
+          # wake to the fork(s) reading that queue; fork-owned listeners take
+          # ->(_channel) and ignore it.
+          @on_wake.call(channel)
         end
         # Skip the keepalive when a stop landed during the wait: the loop is
         # about to exit and close this connection anyway, so the round-trip

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