wurk 1.1.0 → 1.1.2

data/lib/wurk/railtie.rb

@@ -1,60 +1,32 @@
 # frozen_string_literal: true
 
 require 'rails/railtie'
+require 'active_support/ordered_options'
+require_relative 'rails_boot'
 
 module Wurk
-  # Boot the swarm after the host app has fully initialized.
-  # Skip when: WURK_DISABLED=1, Rails console mode, or Rails test env.
+  # Rails integration surface only: register the host-facing `config.wurk`
+  # namespace and wire the two boot hooks to Wurk::RailsBoot. All boot policy
+  # (skip/fork/embed/refuse, prefork detection) and execution lives there — this
+  # class exists solely to invoke the coordinator from the Rails lifecycle.
   # See docs/idea/03-process-model.md for the exact ordering.
   class Railtie < ::Rails::Railtie
-    # This Rails process forks the workers, so it IS the server. Enter server
-    # mode BEFORE config/initializers load — otherwise the app's
-    # `Sidekiq.configure_server` blocks gate on `config.server?` (still false)
-    # and are silently dropped. Gated identically to the swarm boot: a process
-    # that won't run workers (disabled / console / test) is not a server.
-    initializer 'wurk.server_mode', before: :load_config_initializers do
-      Wurk.enter_server_mode unless Wurk::Railtie.skip_boot?
-    end
+    # Host-facing config namespace. Pre-created so a host can write
+    # `config.wurk.embed_in_web = true` in config/application.rb without a
+    # NoMethodError — the setter needs the OrderedOptions to already exist.
+    # Shared with the application config via Rails' Railtie::Configuration
+    # @@options, so `Rails.application.config.wurk` reads back the same object.
+    config.wurk = ::ActiveSupport::OrderedOptions.new
 
-    config.after_initialize do |_app|
-      next if Wurk::Railtie.skip_boot?
-
-      swarm = Wurk::Swarm.new(topology: Wurk.configuration.topology)
-      swarm.boot
-      # Embedded mode keeps the Rails process serving HTTP; supervise must
-      # run somewhere or signal_queue never drains, crashed children never
-      # respawn, and memory pressure checks never fire. Background thread
-      # leaves the host's main thread free for Rails.
-      Thread.new do
-        swarm.supervise
-      rescue StandardError => e
-        Wurk.configuration.logger.error { "wurk supervisor thread died: #{e.class}: #{e.message}" }
-      end
-    end
-
-    # A process that won't run workers isn't a server: skip both server mode
-    # and the swarm boot. Console mode is detected reliably here — the console
-    # command file defines ::Rails::Console before initializers run.
-    def self.skip_boot?
-      ENV['WURK_DISABLED'] == '1' ||
-        building? ||
-        defined?(::Rails::Console) ||
-        ::Rails.env.test?
+    # Enter server mode BEFORE config/initializers load — otherwise the app's
+    # `Sidekiq.configure_server` blocks gate on `config.server?` (still false)
+    # and are silently dropped. RailsBoot decides whether this process serves.
+    initializer 'wurk.server_mode', before: :load_config_initializers do |app|
+      Wurk::RailsBoot.enter_server_mode_if_serving(app)
     end
 
-    # A build/precompile step must never fork the swarm (#247). The default
-    # Rails Dockerfile runs `SECRET_KEY_BASE_DUMMY=1 ./bin/rails
-    # assets:precompile`; that loads `:environment` → fires after_initialize,
-    # but there's no Redis during `docker build`, so a fork would hang/fail the
-    # build. Same for other env-loading rake tasks (db:prepare, db:migrate).
-    # The real server path is unaffected: `rails server` / `puma` boot through
-    # Rails::Command, not Rake, and don't set the dummy secret.
-    def self.building?
-      return true if ENV.key?('SECRET_KEY_BASE_DUMMY')
-
-      defined?(::Rake) && ::Rake.application.top_level_tasks.any?
-    rescue StandardError
-      false
+    config.after_initialize do |app|
+      Wurk::RailsBoot.boot(app)
     end
   end
 end

data/lib/wurk/redis_connection.rb

@@ -10,21 +10,18 @@ module Wurk
   # (connection_pool-backed, redis-client adapter), which is `.with`-compatible
   # with everything that expects a Sidekiq pool.
   #
-  # Accepts Sidekiq's option keys (`url`, `size`, `pool_timeout`, `name`),
-  # string- or symbol-keyed. Anything omitted falls back to RedisPool's defaults
-  # (URL = ENV["REDIS_URL"] or redis://localhost:6379/0).
+  # Accepts Sidekiq's option keys (`url`, `size`, `pool_timeout`, `name`) plus
+  # the socket knobs (`connect_timeout`/`read_timeout`/`write_timeout`/
+  # `reconnect_attempts`/`driver`), string- or symbol-keyed. Anything omitted
+  # falls back to RedisPool's defaults (URL = ENV["REDIS_URL"] or
+  # redis://localhost:6379/0).
   module RedisConnection
     # Housekeeping/standalone default; per-capsule pools size to concurrency.
     DEFAULT_POOL_SIZE = 10
 
     def self.create(options = {})
       opts = options.transform_keys(&:to_sym)
-      RedisPool.new(
-        size: opts[:size] || DEFAULT_POOL_SIZE,
-        url: opts[:url] || RedisPool::DEFAULT_URL,
-        timeout: opts[:pool_timeout] || RedisPool::DEFAULT_TIMEOUT,
-        name: opts[:name] || RedisPool::DEFAULT_NAME
-      )
+      RedisPool.new(size: opts.delete(:size) || DEFAULT_POOL_SIZE, **opts)
     end
   end
 end

data/lib/wurk/redis_pool.rb

@@ -9,41 +9,86 @@ module Wurk
   # across forks: the parent closes the pool before fork, each child opens a
   # fresh one (see docs/idea/03-process-model.md, steps 3 and 5).
   #
-  # Retry policy on conn-level errors: close + retry once for messages
-  # prefixed READONLY / NOREPLICAS / UNBLOCKED. Spec: docs/target/sidekiq-free.md §26.
+  # #with absorbs transient Redis failures (production incident #101):
+  #   * READONLY / NOREPLICAS / UNBLOCKED — a failover happened; close and retry
+  #     once immediately so redis-client redials the new primary (spec §26).
+  #   * ConnectionError (incl. CannotConnect / Read- / WriteTimeout) — a blip;
+  #     close and retry with exponential backoff up to CONN_MAX_ATTEMPTS, then
+  #     raise. At-least-once tolerates the rare duplicate and JobRetry re-runs
+  #     the job anyway, so retrying at the pool layer is strictly better.
+  #   * ConnectionPool::TimeoutError — checkout starved; retry once after a
+  #     short jittered pause, then raise (sizing is the fix, not queuing).
+  # Every retry and final give-up is reported through the injected `on_error`
+  # telemetry hook (Wurk::Configuration#on_redis_error).
   class RedisPool
-    DEFAULT_URL     = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
-    DEFAULT_TIMEOUT = 1.0
-    DEFAULT_NAME    = 'default'
+    DEFAULT_URL  = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
+    DEFAULT_NAME = 'default'
 
-    # Server-side messages where Sidekiq (and therefore Wurk) closes the
-    # connection and retries the block exactly once. Any other RedisClient::Error
-    # propagates immediately.
+    # ConnectionPool checkout wait — how long #with blocks for a free slot.
+    DEFAULT_POOL_TIMEOUT = 1.0
+
+    # Socket-level timeouts handed to RedisClient, split apart from the checkout
+    # wait above. read/write are deliberately wider than connect so a briefly-
+    # slow-but-alive Redis (RDB fork pause, a large BLMOVE payload) doesn't
+    # spuriously ReadTimeout — the production incident (#101) the single
+    # dual-use timeout caused. reconnect_attempts re-dials a dropped socket once.
+    DEFAULT_CONNECT_TIMEOUT    = 1.0
+    DEFAULT_READ_TIMEOUT       = 2.5
+    DEFAULT_WRITE_TIMEOUT      = 2.5
+    DEFAULT_RECONNECT_ATTEMPTS = 1
+
+    # Server-side messages where the connection is closed and the block retried
+    # exactly once. READONLY is itself a RedisClient::ConnectionError subclass,
+    # so this message match must be tested BEFORE the generic ConnectionError
+    # backoff below (otherwise a failover would sleep instead of redialing).
     RETRYABLE_MSG = /\A(READONLY|NOREPLICAS|UNBLOCKED)/
 
-    attr_reader :size, :url, :timeout, :name
+    # ConnectionError backoff: CONN_MAX_ATTEMPTS total tries, sleeping
+    # (BASE * 2**attempt) + rand*JITTER before each retry. The 1.0s + 2.0s pair
+    # rides out a sub-4s blip; the jitter de-syncs a fleet reconnecting at once.
+    CONN_MAX_ATTEMPTS   = 3
+    CONN_BACKOFF_BASE   = 0.5
+    CONN_BACKOFF_JITTER = 0.25
+
+    # Checkout-timeout retry: one retry after a jittered pause in
+    # [POOL_RETRY_MIN, POOL_RETRY_MIN + POOL_RETRY_SPREAD). No loop — sustained
+    # checkout starvation is a sizing bug, not something to queue behind.
+    POOL_RETRY_MIN    = 0.1
+    POOL_RETRY_SPREAD = 0.2
+
+    attr_reader :size, :url, :name, :pool_timeout, :client_config
 
-    def initialize(size:, url: DEFAULT_URL, timeout: DEFAULT_TIMEOUT, name: DEFAULT_NAME)
-      @size    = size
-      @url     = url
-      @timeout = timeout
-      @name    = name
-      @pool    = ConnectionPool.new(size: size, timeout: timeout) { build_client }
+    # Takes the standard Sidekiq `config.redis` hash: `pool_timeout` tunes the
+    # ConnectionPool checkout; `connect_timeout`/`read_timeout`/`write_timeout`/
+    # `reconnect_attempts` plus any other key (driver, ssl_params, …) forward
+    # verbatim to RedisClient.config. `on_error` is an optional callable fired
+    # per retry / final give-up with { error:, attempt:, retried:, pool: }.
+    def initialize(size:, name: DEFAULT_NAME, on_error: nil, **options)
+      @size          = size
+      @name          = name
+      @on_error      = on_error
+      @pool_timeout  = options.fetch(:pool_timeout, DEFAULT_POOL_TIMEOUT)
+      @client_config = build_client_config(options)
+      @url           = @client_config[:url]
+      @pool          = ConnectionPool.new(size: size, timeout: @pool_timeout) { build_client }
     end
 
-    def with
-      @pool.with do |conn|
-        attempts = 0
-        begin
-          yield conn
-        rescue RedisClient::Error => e
-          raise unless RETRYABLE_MSG.match?(e.message.to_s)
-          raise if attempts >= 1
-
-          attempts += 1
-          safe_close(conn)
-          retry
+    # Checkout a connection and run the block. ConnectionPool::TimeoutError is
+    # raised by @pool.with *before* the block runs, so it is caught out here
+    # (the in-block #run rescue never sees it) — one retry, then raise.
+    def with(&block)
+      checkout_retried = false
+      begin
+        @pool.with { |conn| run(conn, &block) }
+      rescue ConnectionPool::TimeoutError => e
+        if checkout_retried
+          notify_error(e, attempt: 2, retried: false)
+          raise
         end
+        checkout_retried = true
+        notify_error(e, attempt: 1, retried: true)
+        sleep(checkout_delay)
+        retry
       end
     end
 
@@ -51,17 +96,40 @@ module Wurk
       @pool.shutdown { |conn| safe_close(conn) }
     end
 
+    # Redis INFO parsed to a Hash, with this pool's own `size` / `available`
+    # slot counts merged in — one call gives a heartbeat both Redis health and
+    # local pool saturation. (Real Redis INFO has no `size`/`available` field.)
     def info
       with { |conn| parse_info(conn.call('INFO')) }
+        .merge('size' => @size, 'available' => available)
+    end
+
+    # Free (unchecked-out) slots right now. Local and cheap — no Redis round
+    # trip — so a monitor can poll it without perturbing the pool.
+    def available
+      @pool.available
     end
 
     private
 
+    # Socket config forwarded to RedisClient.config. Host-supplied keys win over
+    # the defaults; `pool_timeout` is dropped (it's a pool concern, not a socket
+    # one) and unknown keys pass straight through.
+    def build_client_config(options)
+      {
+        url: DEFAULT_URL,
+        connect_timeout: DEFAULT_CONNECT_TIMEOUT,
+        read_timeout: DEFAULT_READ_TIMEOUT,
+        write_timeout: DEFAULT_WRITE_TIMEOUT,
+        reconnect_attempts: DEFAULT_RECONNECT_ATTEMPTS
+      }.merge(options.except(:pool_timeout)).freeze
+    end
+
     # Wrapped in the CompatClient decorator so `Sidekiq.redis { |c| c.smembers }`
     # method-style commands work like Sidekiq 7+ (#204). Wurk's own code paths
     # use #call, which the decorator forwards.
     def build_client
-      RedisClientAdapter::CompatClient.new(RedisClient.config(url: @url, timeout: @timeout).new_client)
+      RedisClientAdapter::CompatClient.new(RedisClient.config(**@client_config).new_client)
     end
 
     def safe_close(conn)
@@ -70,6 +138,58 @@ module Wurk
       nil
     end
 
+    # Runs the block on the checked-out `conn`, retrying transient RedisClient
+    # errors in place: the same slot is reused across retries (redis-client
+    # redials a closed socket lazily), so a busy fetcher can't leak checkouts.
+    def run(conn)
+      attempts = 0
+      begin
+        attempts += 1
+        yield conn
+      rescue RedisClient::Error => e
+        plan = retry_plan(e, attempts)
+        raise if plan == :propagate
+
+        notify_error(e, attempt: attempts, retried: plan != :exhausted)
+        raise if plan == :exhausted
+
+        safe_close(conn)
+        sleep(backoff_delay(attempts)) if plan == :backoff
+        retry
+      end
+    end
+
+    # Pure classification of a RedisClient error against the attempt count:
+    #   :failover  → close + immediate retry (a primary swap)
+    #   :backoff   → close + sleep + retry (a connection blip)
+    #   :exhausted → ConnectionError past the cap; report and give up
+    #   :propagate → not transient (or a spent failover); raise as-is
+    def retry_plan(err, attempts)
+      if RETRYABLE_MSG.match?(err.message.to_s)
+        attempts > 1 ? :propagate : :failover
+      elsif err.is_a?(RedisClient::ConnectionError)
+        attempts >= CONN_MAX_ATTEMPTS ? :exhausted : :backoff
+      else
+        :propagate
+      end
+    end
+
+    def notify_error(error, attempt:, retried:)
+      return if @on_error.nil?
+
+      @on_error.call({ error:, attempt:, retried:, pool: @name })
+    rescue StandardError
+      nil
+    end
+
+    def backoff_delay(attempt)
+      (CONN_BACKOFF_BASE * (2**attempt)) + (rand * CONN_BACKOFF_JITTER)
+    end
+
+    def checkout_delay
+      POOL_RETRY_MIN + (rand * POOL_RETRY_SPREAD)
+    end
+
     def parse_info(raw)
       raw.to_s.each_line.with_object({}) do |line, h|
         line = line.strip

data/lib/wurk/scheduled.rb

@@ -39,9 +39,7 @@ module Wurk
       # client. `now` is captured once per set so a slow loop on one ZSET
       # can't keep grabbing newly-scheduled jobs from a moving window.
       def enqueue_jobs(sorted_sets = SETS)
-        @config.redis do |conn|
-          sorted_sets.each { |sset| drain_set(conn, sset) }
-        end
+        sorted_sets.each { |sset| drain_set(sset) }
       end
 
       def terminate
@@ -50,18 +48,34 @@ module Wurk
 
       private
 
-      def drain_set(conn, sset)
+      # Pop under one checkout (the pooled EVALSHA loop), push outside it —
+      # `@client.push` checks out its own connection, so nesting it inside
+      # `@config.redis` would hold two checkouts from the same pool at once
+      # per job, halving effective pool concurrency under load.
+      def drain_set(sset)
         now = real_time.to_s
         loop do
           break if @done
 
-          jobstr = Wurk::Lua::Loader.eval_cached(conn, :zpopbyscore, keys: [sset], argv: [now])
+          jobstr = @config.redis { |conn| Wurk::Lua::Loader.eval_cached(conn, :zpopbyscore, keys: [sset], argv: [now]) }
           break unless jobstr
 
-          @client.push(Wurk.load_json(jobstr))
+          push_promoted(jobstr, sset)
         end
       end
 
+      # A raising `@client.push` (bad payload, transient Redis error) must not
+      # abort the drain and strand the remaining due jobs until the next poll —
+      # rescue per-job, report, continue. The already-popped job IS lost here
+      # (ZPOPBYSCORE removed it); that pop→push loss window is the default
+      # scheduler's known tradeoff — `reliable_scheduler!` (ReliableEnq) is the
+      # loss-free fix, so we don't re-engineer around it here.
+      def push_promoted(jobstr, sset)
+        @client.push(Wurk.load_json(jobstr))
+      rescue StandardError => e
+        handle_exception(e, { context: 'scheduler_promote', set: sset })
+      end
+
       def real_time
         ::Process.clock_gettime(::Process::CLOCK_REALTIME)
       end
@@ -78,6 +92,12 @@ module Wurk
     class ReliableEnq
       include Component
 
+      # Batched: each Lua call promotes at most this many members (the script
+      # runs atomically, so one giant sweep would stall Redis for every
+      # client). `promote` loops until a short batch signals the backlog is
+      # dry, stopping early on terminate.
+      PROMOTE_BATCH = 500
+
       def initialize(container)
         @config = container
         @done = false
@@ -96,12 +116,15 @@ module Wurk
       private
 
       def promote(conn, sset)
-        Wurk::Lua::Loader.eval_cached(
-          conn,
-          :reliable_schedule_promote,
-          keys: [sset, Keys::QUEUES_SET],
-          argv: [real_time.to_s, Keys::QUEUE_PREFIX]
-        )
+        loop do
+          promoted = Wurk::Lua::Loader.eval_cached(
+            conn,
+            :reliable_schedule_promote,
+            keys: [sset, Keys::QUEUES_SET],
+            argv: [real_time.to_s, Keys::QUEUE_PREFIX, real_ms.to_s, PROMOTE_BATCH.to_s]
+          ).to_i
+          break if promoted < PROMOTE_BATCH || @done
+        end
       end
 
       def real_time

data/lib/wurk/swarm/backoff.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Wurk
+  class Swarm
+    # Per-key exponential backoff timer with survival-based reset. Pure
+    # bookkeeping — no sleeping, no I/O — so the supervise thread never blocks
+    # on it: it records a failure, then asks `ready?` each tick and acts only
+    # once the delay has elapsed.
+    #
+    # Delay grows base → 2·base → 4·base … capped at `cap`. A key whose child
+    # survived at least `reset_after` seconds counts as a fresh first failure,
+    # so a slot that ran healthily for a while doesn't inherit an old crash
+    # streak. Keyed by slot index for crash-respawn and (in Swarm::Restart) for
+    # replacement-retry delays.
+    class Backoff
+      BASE = 1.0
+      CAP = 30.0
+      RESET_AFTER = 60.0
+
+      def initialize(base: BASE, cap: CAP, reset_after: RESET_AFTER, clock: nil)
+        @base = base
+        @cap = cap
+        @reset_after = reset_after
+        @clock = clock || -> { ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) }
+        @streak = Hash.new(0)
+        @due_at = {}
+      end
+
+      # Record a failure and schedule the next attempt. `lifetime` is how long
+      # the failed child lived; >= reset_after resets the streak. Returns the
+      # delay applied.
+      def fail(key, lifetime: 0.0)
+        @streak[key] = 0 if lifetime >= @reset_after
+        @streak[key] += 1
+        delay = [@base * (2**(@streak[key] - 1)), @cap].min
+        @due_at[key] = now + delay
+        delay
+      end
+
+      # A retry is scheduled and not yet issued.
+      def pending?(key)
+        @due_at.key?(key)
+      end
+
+      # The scheduled delay has elapsed (or nothing is scheduled).
+      def ready?(key)
+        at = @due_at[key]
+        at.nil? || now >= at
+      end
+
+      # Mark the scheduled retry as issued without resetting the streak, so a
+      # child that crashes straight back escalates toward the cap.
+      def consume(key)
+        @due_at.delete(key)
+      end
+
+      # Forget the key entirely (slot retired or restart succeeded).
+      def clear(key)
+        @streak.delete(key)
+        @due_at.delete(key)
+      end
+
+      private
+
+      def now
+        @clock.call
+      end
+    end
+  end
+end

data/lib/wurk/swarm/child_boot.rb

@@ -3,6 +3,8 @@
 require_relative '../component'
 require_relative '../launcher'
 require_relative '../fetcher/reliable'
+require_relative '../lua'
+require_relative 'orphan_guard'
 
 module Wurk
   class Swarm
@@ -21,11 +23,23 @@ module Wurk
 
       CHILD_SIGNALS = { 'TERM' => :term, 'INT' => :term, 'TSTP' => :tstp, 'USR2' => :usr2 }.freeze
 
-      def initialize(config, slot, index)
+      # `parent_pid` is captured by the swarm before it forks (race-free) and
+      # threaded through so OrphanGuard can tell "still supervised" from
+      # "reparented after the supervisor died". Defaults to the live parent for
+      # the non-swarm callers (tests) that construct a ChildBoot directly.
+      # `start_quiet:` — the swarm was TSTP-quieted before this child was
+      # forked (respawn/recycle during maintenance); boot the launcher already
+      # quieted so the replacement doesn't resume fetching. Delivered as a
+      # constructor flag, not a post-fork TSTP, because the signal would race
+      # the trap-reset window (default TSTP disposition suspends the child).
+      def initialize(config, slot, index, parent_pid: ::Process.ppid, start_quiet: false)
         @config = config
         @slot = slot
         @index = index
-        @signal_queue = ::Thread::Queue.new
+        @parent_pid = parent_pid
+        @start_quiet = start_quiet
+        @signal_read = nil
+        @signal_write = nil
       end
 
       def run
@@ -56,28 +70,71 @@ module Wurk
 
       # Boot the launcher and block until shutdown. wait_loop joins the
       # signal-dispatch thread, so the child can't fall through to `exit 0`
-      # mid-drain.
+      # mid-drain. Orphan protection is armed right AFTER launcher.run — the
+      # TERM handler is in place (so pdeathsig / the watchdog drain gracefully)
+      # and the managers are up (so a self-TERM can't race launcher.run). A
+      # parent that died during boot is still caught immediately: the watchdog's
+      # first getppid check sees the reparent and drains at once.
       def run_launcher
         launcher = Wurk::Launcher.new(@config)
         install_signal_handlers(launcher)
         launcher.run
+        launcher.quiet if @start_quiet
+        arm_orphan_guard
         wait_loop(launcher)
       end
 
-      # Parent installed traps for TERM/INT/TSTP/CONT/USR1 — the child
-      # needs its own behavior, not the parent's.
+      def arm_orphan_guard
+        @orphan_guard = OrphanGuard.new(@parent_pid, logger: @config.logger)
+        @watchdog = @orphan_guard.arm
+      end
+
+      # Parent installed traps for TERM/INT/TSTP — the child needs its own
+      # behavior, not the parent's. USR2 too: the child owns log-reopen.
+      # USR1 (rolling restart) is a no-op in the child — trap it with a log
+      # so stray USR1s don't trigger default termination.
       def reset_inherited_signals
-        %w[TERM INT TSTP CONT USR1 USR2].each { |s| ::Signal.trap(s, 'DEFAULT') }
+        %w[TERM INT TSTP USR2].each { |s| ::Signal.trap(s, 'DEFAULT') }
+        # A genuine no-op in the child (rolling restart is the parent's job) —
+        # trap it empty so a stray USR1 can't fall through to default
+        # termination. Must NOT log: Logger synchronizes writes and would
+        # deadlock if the trap fired mid-write.
+        ::Signal.trap('USR1') { nil }
+      rescue ArgumentError
+        nil
       end
 
       def reconnect_after_fork
         @config.reset_redis_pools!
+        validate_redis!
+        reconnect_active_record
+      end
+
+      # Prove the child's fresh Redis socket reaches a live server before it
+      # starts fetching: one PING through RedisPool#with, which owns the
+      # retry+backoff (production incident #101), so a transient blip during
+      # boot rides out instead of racing straight into a dead pool. A PING that
+      # still fails past the wrapper's retries propagates and crashes the child
+      # (the swarm respawns it) rather than booting a worker that can't reach
+      # Redis. The same checkout eagerly primes every Lua script in one
+      # pipelined round-trip so the first EVALSHA hits a warm cache.
+      def validate_redis!
+        @config.redis_pool.with do |conn|
+          conn.call('PING')
+          Wurk::Lua::Loader.script_load_all(conn)
+        end
+      end
+
+      # AR reconnect is best-effort — a Redis-only worker with no database still
+      # runs — but the silent `rescue nil` here hid a real misconfiguration
+      # during the #101 audit, so warn loudly instead of swallowing.
+      def reconnect_active_record
         return unless defined?(::ActiveRecord::Base)
 
-        begin
-          ::ActiveRecord::Base.establish_connection
-        rescue StandardError
-          nil
+        ::ActiveRecord::Base.establish_connection
+      rescue StandardError => e
+        @config.logger.warn do
+          "swarm child ##{@index} (#{::Process.pid}) ActiveRecord reconnect failed: #{e.class}: #{e.message}"
         end
       end
 
@@ -90,11 +147,29 @@ module Wurk
         # below — for every entry point, not just the swarm.
       end
 
+      # Self-pipe pattern (same as Wurk::CLI / Wurk::Swarm): the trap only
+      # writes the signal name to a pipe — never Thread::Queue#push, whose
+      # mutex a trap can deadlock against.
       def install_signal_handlers(launcher)
-        CHILD_SIGNALS.each { |sig, sym| ::Signal.trap(sig) { @signal_queue << sym } }
+        @signal_read, @signal_write = ::IO.pipe
+        CHILD_SIGNALS.each_key do |sig|
+          ::Signal.trap(sig) { emit_signal(sig) }
+        rescue ArgumentError
+          nil
+        end
         @dispatcher = Thread.new { dispatch_signals(launcher) }
       end
 
+      # Non-blocking self-pipe write from trap context: a blocking `puts` could
+      # stall the TERM drain if the pipe ever filled. `exception: false` returns
+      # :wait_writable instead of raising when full (the queued duplicate
+      # coalesces); a closed pipe during shutdown is ignored too.
+      def emit_signal(sig)
+        @signal_write.write_nonblock("#{sig}\n", exception: false)
+      rescue ::IOError, ::Errno::EPIPE, ::Errno::EBADF
+        nil
+      end
+
       # TSTP/USR2 keep looping; TERM/INT run the full launcher.stop
       # (which blocks on manager drain) and then return — wait_loop
       # joins this thread, so the main child thread can't `exit 0`
@@ -102,10 +177,14 @@ module Wurk
       # and the main thread would race past the unfinished managers.
       def dispatch_signals(launcher)
         loop do
-          case @signal_queue.pop
+          @signal_read.wait_readable
+          sig = @signal_read.gets&.strip
+          break if sig.nil?
+
+          case CHILD_SIGNALS[sig]
           when :term
             launcher.stop
-            return
+            break
           when :tstp then launcher.quiet
           when :usr2 then reopen_logs
           end