wurk 0.0.5 → 1.0.0

data/lib/wurk/cli.rb

@@ -93,6 +93,12 @@ module Wurk
 
     # `boot_app:` / `warmup:` are test seams. Production always passes true.
     def run(boot_app: true, warmup: true)
+      # Mark server mode BEFORE the app loads so `configure_server` blocks in
+      # the required initializer actually fire (they gate on `config.server?`).
+      # Matches Sidekiq, which sets `Sidekiq.server = true` before requiring
+      # the app in its CLI. Skipping this silently drops server middleware,
+      # error handlers, and lifecycle hooks registered via configure_server.
+      enter_server_mode
       boot_application if boot_app
       self_read, self_write = ::IO.pipe
       trap_signals(self_write)
@@ -107,6 +113,35 @@ module Wurk
       launch(self_read)
     end
 
+    # Standalone multi-process boot — the `sidekiqswarm` entry point (Ent §7).
+    # The parent loads the app once, forks N worker children per the configured
+    # topology, then supervises them (respawn on crash, rolling restart on
+    # SIGUSR1, memory-based recycling). The parent itself never fetches.
+    #
+    # This is the only way to get fork-based parallelism without Rails — the
+    # railtie auto-boot path is Rails-only. Honors the swarm preload knobs
+    # (`WURK_PRELOAD`/`SIDEKIQ_PRELOAD` Bundler groups, `WURK_PRELOAD_APP`/
+    # `SIDEKIQ_PRELOAD_APP` whole-app eager-load) and boots `Process.warmup`
+    # before the fork so children share warmed pages (copy-on-write). Spec §7.
+    def run_swarm(boot_app: true, warmup: true)
+      # Server mode before the app loads — see #run. The flag rides through the
+      # fork into every child (the config object is copied), so configure_server
+      # blocks registered in the parent take effect in the workers.
+      enter_server_mode
+      if boot_app
+        preload_bundler_groups
+        boot_application
+        eager_load_application
+      end
+      validate_redis!
+      validate_pool_sizes!
+      @config[:identity] = identity
+      ::Process.warmup if warmup && ::Process.respond_to?(:warmup) && ENV['RUBY_DISABLE_WARMUP'] != '1'
+      @swarm = Wurk::Swarm.new(topology: @config.topology, config: @config)
+      @swarm.boot(install_signals: true)
+      @swarm.supervise
+    end
+
     def handle_signal(sig)
       logger.debug { "Got #{sig} signal" }
       handler = SIGNAL_HANDLERS[sig]
@@ -119,8 +154,11 @@ module Wurk
 
     # --- run helpers ----------------------------------------------------
 
+    def enter_server_mode
+      Wurk.enter_server_mode(@config)
+    end
+
     def launch(self_read)
-      Wurk.server = true
       @launcher = Wurk::Launcher.new(@config)
       begin
         @launcher.run
@@ -299,6 +337,51 @@ module Wurk
 
     # --- application bootstrap --------------------------------------------
 
+    # Spec §7.2/§7.3. Before the swarm parent forks, `Bundler.require` the
+    # configured groups so their gems are resident in the parent and paged
+    # copy-on-write into every child. Comma-separated group list; the native
+    # `WURK_PRELOAD` wins over the `SIDEKIQ_PRELOAD` drop-in alias. Defaults to
+    # the `default` group; an explicit empty value (`WURK_PRELOAD=`) disables
+    # the preload. Runs before `boot_application` so groups load before the app.
+    def preload_bundler_groups
+      return unless defined?(::Bundler)
+
+      groups = preload_groups
+      ::Bundler.require(*groups) unless groups.empty?
+    end
+
+    def preload_groups
+      raw = ENV['WURK_PRELOAD'] || ENV['SIDEKIQ_PRELOAD'] || 'default'
+      raw.split(',').map(&:strip).reject(&:empty?).map(&:to_sym)
+    end
+
+    # Spec §7.2. `WURK_PRELOAD_APP=1` (alias `SIDEKIQ_PRELOAD_APP=1`) eager-loads
+    # the whole Rails app in the parent before forking, so the entire object
+    # space — not just the constants autoload happened to touch — is shared
+    # copy-on-write, trading parent boot time for child RSS savings (~20–30%).
+    #
+    # Intentional divergence from Sidekiq's default-0: wurk's swarm forks
+    # children from a preloaded parent — they inherit the app rather than
+    # re-requiring it — so the app entrypoint (`-r`) is always loaded in the
+    # parent regardless of this flag. PRELOAD_APP only toggles the extra Rails
+    # eager-load; for a non-Rails `-r` file there is nothing further to load.
+    def eager_load_application
+      return unless preload_app?
+
+      app = rails_application
+      app.eager_load! if app.respond_to?(:eager_load!)
+    end
+
+    def rails_application
+      return unless defined?(::Rails) && ::Rails.respond_to?(:application)
+
+      ::Rails.application
+    end
+
+    def preload_app?
+      (ENV['WURK_PRELOAD_APP'] || ENV.fetch('SIDEKIQ_PRELOAD_APP', nil)) == '1'
+    end
+
     # Standalone mode must NOT load wurk/rails — even when pointed at a Rails
     # app, that's the host's call to wire the railtie. The CLI only `require`s
     # the host's entrypoint and reads the resulting classes.

data/lib/wurk/client.rb

@@ -266,19 +266,18 @@ module Wurk
 
     # Outside of test boots and `SCRIPT FLUSH` the rescue branch is dead
     # code; the eager `script_load_all` after fork keeps the script cache
-    # hot for the life of the connection.
+    # hot for the life of the connection. The retry uses EVAL (source-embedded)
+    # instead of EVALSHA so a freshly-loaded script can't race the retry and
+    # NOSCRIPT a second time under heavy CI load (WorkerTest 3.4/7.2 flake).
+    # `script_load_all` still primes the cache so the *next* pipeline returns
+    # to the EVALSHA fast path.
     def push_batched_pipelined(conn, batched, now)
-      attempts = 0
-      begin
-        conn.pipelined { |pipe| push_batched(pipe, batched, now) }
-      rescue RedisClient::CommandError => e
-        raise unless e.message.to_s.start_with?('NOSCRIPT')
-        raise if attempts.positive?
-
-        attempts += 1
-        Wurk::Lua::Loader.script_load_all(conn)
-        retry
-      end
+      conn.pipelined { |pipe| push_batched(pipe, batched, now) }
+    rescue RedisClient::CommandError => e
+      raise unless e.message.to_s.start_with?('NOSCRIPT')
+
+      Wurk::Lua::Loader.script_load_all(conn)
+      conn.pipelined { |pipe| push_batched(pipe, batched, now, eval_method: :eval_with_source) }
     end
 
     def push_plain(conn, payloads, now)
@@ -297,15 +296,19 @@ module Wurk
     # SADDs jid into the live set, registers the queue, LPUSHes the payload —
     # all atomically. One Redis round-trip per job (no pipeline grouping)
     # because the lua needs per-job KEYS bound. Acceptable cost: batch
-    # enqueue is not the hot path; correctness is.
-    def push_batched(conn, payloads, now)
+    # enqueue is not the hot path; correctness is. `eval_method` is the
+    # Wurk::Lua::Loader entry point (`:eval_cached` for the hot EVALSHA path,
+    # `:eval_with_source` for the EVAL-source retry).
+    def push_batched(conn, payloads, now, eval_method: :eval_cached)
       payloads.each do |j|
         j['enqueued_at'] = now
-        Wurk::Lua::Loader.eval_cached(
+        Wurk::Lua::Loader.public_send(
+          eval_method,
           conn,
           :batch_push,
-          keys: ["b-#{j['bid']}", "b-#{j['bid']}-jids", "queue:#{j['queue']}", 'queues'],
-          argv: [j['queue'], j['jid'], Wurk.dump_json(j)]
+          keys: ["b-#{j['bid']}", "b-#{j['bid']}-jids", "queue:#{j['queue']}", 'queues',
+                 "b-#{j['bid']}-died", 'dead-batches'],
+          argv: [j['queue'], j['jid'], Wurk.dump_json(j), j['bid']]
         )
       end
     end

data/lib/wurk/compat.rb

@@ -18,7 +18,30 @@ module Sidekiq
   # Sidekiq::Enterprise::Crypto, …). Defined so downstream code can nest
   # classes under them — but `Sidekiq.pro?` / `Sidekiq.ent?` still return
   # `false` per docs/target/sidekiq-free.md §32 (Wurk advertises as free OSS).
-  module Pro; end
+  module Pro
+    # Sidekiq Pro mounts the dashboard at `Sidekiq::Pro::Web`; it's the same
+    # board as `Sidekiq::Web` here, so a Pro app's `mount Sidekiq::Pro::Web`
+    # drops in unchanged. `Wurk::Web` is already required by the time this file
+    # loads (lib/wurk.rb requires wurk/web before wurk/compat).
+    Web = Wurk::Web
+
+    # `use Sidekiq::Pro::BatchStatus` — the polling Rack middleware that serves
+    # GET /batch_status/<bid>.json. Spec: docs/target/sidekiq-pro.md §10.3.
+    BatchStatus = Wurk::Web::BatchStatus
+
+    # Pro module-level statsd accessor (spec §1): `Sidekiq::Pro.dogstatsd = ...`.
+    # Delegates to the canonical `config.dogstatsd=` (spec §9.1), so either form
+    # feeds the same Wurk::Metrics::Statsd client.
+    class << self
+      def dogstatsd=(builder)
+        Wurk.configuration.dogstatsd = builder
+      end
+
+      def dogstatsd
+        Wurk.configuration.dogstatsd
+      end
+    end
+  end
 
   # Sidekiq Enterprise feature surface (`unique!`, `Crypto`, `Unique.locked?`).
   # Wurk ships these free; the namespace exists for drop-in compat.
@@ -68,13 +91,19 @@ module Sidekiq
   Component        = Wurk::Component
   Config           = Wurk::Configuration
   Context          = Wurk::Context
-  Cron             = Wurk::Cron
+  # No `Sidekiq::Cron` alias on purpose (#204): real Sidekiq never defines it
+  # — that namespace belongs to the third-party sidekiq-cron gem, and squatting
+  # it made the gem's own classes (Poller, Job) collide at load. Wurk's native
+  # periodic surface is `Sidekiq::Periodic` (Ent parity) / `Wurk::Cron`.
+  CronParser       = Wurk::Cron::Parser
   Periodic         = Wurk::Cron
   DeadSet          = Wurk::DeadSet
   Deploy           = Wurk::Deploy
   Embedded         = Wurk::Embedded
   Encryption       = Wurk::Encryption
+  History          = Wurk::History
   IterableJob      = Wurk::IterableJob
+  IterableJobQuery = Wurk::IterableJobQuery
   Job              = Wurk::Job
   JobLogger        = Wurk::JobLogger
   JobRecord        = Wurk::JobRecord
@@ -92,13 +121,20 @@ module Sidekiq
   Process          = Wurk::Process
   ProcessSet       = Wurk::ProcessSet
   Processor        = Wurk::Processor
+  Profiler         = Wurk::Profiler
+  ProfileSet       = Wurk::ProfileSet
+  ProfileRecord    = Wurk::ProfileRecord
   Queue            = Wurk::Queue
+  RedisClientAdapter = Wurk::RedisClientAdapter
+  RedisConnection  = Wurk::RedisConnection
   RetrySet         = Wurk::RetrySet
   Scheduled        = Wurk::Scheduled
   ScheduledSet     = Wurk::ScheduledSet
   Shutdown         = Wurk::Shutdown
+  SortedEntry      = Wurk::SortedEntry
   Stats            = Wurk::Stats
   Testing          = Wurk::Testing
+  TransactionAwareClient = Wurk::TransactionAwareClient
   Queues           = Wurk::Queues
   EmptyQueueError  = Wurk::Testing::EmptyQueueError
   Web              = Wurk::Web
@@ -118,6 +154,11 @@ module Sidekiq
     def redis(&) = Wurk.redis(&)
     def redis_pool = Wurk.redis_pool
     def logger = Wurk.logger
+
+    def logger=(logger)
+      Wurk.logger = logger
+    end
+
     def server? = Wurk.server?
     def pro? = Wurk.pro?
     def ent? = Wurk.ent?
@@ -128,6 +169,7 @@ module Sidekiq
     end
 
     def strict_args!(mode = :raise) = Wurk.strict_args!(mode)
+    def transactional_push! = Wurk.transactional_push!
     def testing!(mode = :fake, &) = Wurk.testing!(mode, &)
     def testing? = Wurk.testing?
     def load_json(str) = Wurk.load_json(str)

data/lib/wurk/component.rb

@@ -73,13 +73,14 @@ module Wurk
     # True iff this process currently holds the cluster `dear-leader` lock.
     # Per spec, the check is performed at call time (Wurk does not cache);
     # callers must not poll faster than the 60s follower cadence. Returns
-    # false unconditionally when `WURK_LEADER=false` is set on the process
-    # (opt-out hot-standby). Any Redis error is swallowed → false, so a
-    # transient partition can't propagate as an exception into user code.
+    # false unconditionally when `WURK_LEADER=false` (or `SIDEKIQ_LEADER=false`)
+    # is set on the process (opt-out hot-standby). Any Redis error is swallowed →
+    # false, so a transient partition can't propagate as an exception into user
+    # code.
     #
     # Spec: docs/target/sidekiq-ent.md §6.1.
     def leader?
-      return false if ENV[Wurk::Leader::OPT_OUT_ENV].to_s.downcase == 'false'
+      return false if Wurk::Leader.opted_out?
 
       redis { |c| c.call('GET', Wurk::Leader::DEFAULT_KEY) } == identity
     rescue StandardError

data/lib/wurk/configuration.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'etc'
 require 'logger'
 require_relative 'middleware/chain'
 require_relative 'capsule'
@@ -29,6 +30,7 @@ module Wurk
       death_handlers: [],
       lifecycle_events: {
         startup: [],
+        fork: [],
         quiet: [],
         shutdown: [],
         exit: [],
@@ -44,7 +46,9 @@ module Wurk
       redis_idle_timeout: nil
     }.freeze
 
-    LIFECYCLE_EVENTS = %i[startup quiet shutdown exit heartbeat beat leader].freeze
+    # :fork fires only inside swarm children, after fork + internal AR/Redis
+    # reconnect — apps reopen sockets / non-fork-safe libs there (Ent §7.4).
+    LIFECYCLE_EVENTS = %i[startup fork quiet shutdown exit heartbeat beat leader].freeze
     DEFAULT_THREAD_PRIORITY = -1
 
     # Default error handler. Wraps the report in the thread-local
@@ -62,7 +66,7 @@ module Wurk
       end
     end
 
-    attr_reader :capsules, :directory, :redis_config
+    attr_reader :capsules, :directory, :redis_config, :super_fetch_callback
     attr_accessor :thread_priority
 
     # Pro parity: callable that builds the statsd / dogstatsd client.
@@ -204,6 +208,45 @@ module Wurk
       @options[:average_scheduled_poll_interval] = interval
     end
 
+    # Reliable-fetch empty-poll backoff: the BLMOVE block timeout (seconds)
+    # used when every served queue is empty. Pro super_fetch §3.3's
+    # `fetch_poll_interval` knob. Unset (nil) → the fetcher's default
+    # (Wurk::Fetcher::Reliable::TIMEOUT, 2s). Also readable as
+    # `config[:fetch_poll_interval]`.
+    def fetch_poll_interval=(seconds)
+      @options[:fetch_poll_interval] = seconds
+    end
+
+    def fetch_poll_interval
+      @options[:fetch_poll_interval]
+    end
+
+    # --- Reliability (Sidekiq Pro drop-in no-ops) ------------------------
+
+    # Sidekiq Pro's opt-in toggles for reliable fetch and the reliable
+    # scheduler. Both are already the default in Wurk — the fetcher is always
+    # the reliable BLMOVE fetcher with orphan reclamation, and the scheduler is
+    # always atomic Lua — so the toggle itself is a no-op. They exist only so a
+    # Pro initializer drops in unchanged instead of raising NoMethodError.
+    #
+    # The optional block is Pro's recovery callback: `|jobstr, pill|`, fired
+    # once per orphan recovery (`pill` nil) and once on a poison kill (`pill`
+    # responds to .jid/.klass/.count/.queue). The reaper drives it via
+    # Wurk::Middleware::PoisonPill.track!. Spec: docs/target/sidekiq-pro.md §3.1.
+    def super_fetch!(*, &block)
+      @super_fetch_callback = block if block
+      nil
+    end
+
+    # Pro reliable scheduler (§4): promote due jobs from retry/schedule onto
+    # their target queue in a single atomic Lua (ZRANGEBYSCORE+ZREM+LPUSH),
+    # closing the pop→push job-loss window of the default poller. Swaps the
+    # pluggable `scheduled_enq` for the atomic promoter; idempotent.
+    def reliable_scheduler!(*)
+      self[:scheduled_enq] = Wurk::Scheduled::ReliableEnq
+      nil
+    end
+
     # --- Periodic (Cron) registration ------------------------------------
 
     # Yields a Wurk::Cron::Manager so the host app can register periodic
@@ -218,6 +261,32 @@ module Wurk
       @periodic_manager
     end
 
+    # --- Historical metrics snapshotter (Ent §5) -------------------------
+
+    HISTORY_DEFAULT_INTERVAL = 30
+
+    # Enables the Ent Historical Metrics snapshotter: every `seconds` the
+    # cluster leader emits a statsd-shaped snapshot to the configured
+    # `dogstatsd` client. With no block the default §5.2 gauge set is
+    # published; a block receives the dogstatsd client `s` and collects
+    # custom metrics instead. The Launcher starts the snapshotter only when
+    # this has been called.
+    #
+    # Spec: docs/target/sidekiq-ent.md §5.1.
+    def retain_history(seconds = HISTORY_DEFAULT_INTERVAL, &block)
+      guard_frozen!
+      interval = Float(seconds)
+      raise ArgumentError, 'retain_history interval must be > 0' unless interval.positive?
+
+      @options[:history_interval] = interval
+      @options[:history_collector] = block
+      nil
+    end
+
+    def history_enabled? = @options.key?(:history_interval)
+    def history_interval = @options.fetch(:history_interval, HISTORY_DEFAULT_INTERVAL)
+    def history_collector = @options[:history_collector]
+
     # --- Web dashboard ----------------------------------------------------
 
     # Web UI configuration: the authorization hook and read-only mode. Returns
@@ -312,6 +381,26 @@ module Wurk
       @topology = value
     end
 
+    # Memory-based child recycling (Sidekiq Ent §7.5): the swarm parent TERMs
+    # (and respawns) any child whose RSS exceeds this many MB. Set in code or
+    # via SIDEKIQ_MAXMEM_MB (WURK_MAXMEM_MB is the native alias); an explicit
+    # value wins over the env. nil/0 disables recycling (the default).
+    def memory_limit_mb
+      @memory_limit_mb || env_memory_limit_mb
+    end
+
+    def memory_limit_mb=(value)
+      guard_frozen!
+      @memory_limit_mb = value.nil? ? nil : Integer(value)
+    end
+
+    # Threshold in KB, the unit the swarm compares against /proc/<pid>/statm
+    # (pages × 4KB). nil when recycling is disabled.
+    def memory_limit_kb
+      mb = memory_limit_mb
+      mb&.positive? ? mb * 1024 : nil
+    end
+
     def freeze!
       return self if @frozen
 
@@ -338,7 +427,35 @@ module Wurk
     # a topology. queue_specs (not queues) so weights survive the round-trip.
     def default_topology
       cap = default_capsule
-      Wurk::Topology.flat(count: 1, queues: cap.queue_specs, concurrency: cap.concurrency)
+      Wurk::Topology.flat(count: default_child_count, queues: cap.queue_specs, concurrency: cap.concurrency)
+    end
+
+    # Number of swarm children when the host hasn't declared a topology
+    # (Sidekiq Ent §7.2). Defaults to the CPU count. A whole number is an
+    # absolute count; a fractional value is a CPU multiplier (e.g. `0.5` → half
+    # the cores, rounded), supported since Sidekiq 8.0.2. WURK_COUNT is the
+    # native name, SIDEKIQ_COUNT the drop-in alias. Unparseable input falls back
+    # to the CPU count; the result is floored at 1 so the swarm always forks.
+    def default_child_count
+      raw = ENV['WURK_COUNT'] || ENV['SIDEKIQ_COUNT']
+      return Etc.nprocessors if raw.nil? || raw.strip.empty?
+
+      value = Float(raw)
+      count = (value % 1).zero? ? value.to_i : (value * Etc.nprocessors).round
+      [count, 1].max
+    rescue ArgumentError, TypeError
+      Etc.nprocessors
+    end
+
+    # SIDEKIQ_MAXMEM_MB is the drop-in name; WURK_MAXMEM_MB the native alias.
+    # Unparseable / empty input disables recycling rather than raising at boot.
+    def env_memory_limit_mb
+      raw = ENV['WURK_MAXMEM_MB'] || ENV['SIDEKIQ_MAXMEM_MB']
+      return nil if raw.nil? || raw.strip.empty?
+
+      Integer(raw)
+    rescue ArgumentError, TypeError
+      nil
     end
 
     def guard_frozen!

data/lib/wurk/cron.rb

@@ -92,6 +92,16 @@ module Wurk
         nil
       end
 
+      # Sidekiq Ent `Sidekiq::CronParser#next`: the next fire Time strictly
+      # after `from` (default now), or nil if the schedule never matches within
+      # the lookahead window. `tz` evaluates the schedule in a timezone (an
+      # AS::TimeZone / TZInfo::Tz / IANA String); default is UTC. Thin wrapper
+      # over `next_fire_at` so there's a single crontab parser.
+      def next(from = ::Time.now, tz = nil)
+        epoch = next_fire_at(from.to_i, tz)
+        epoch && ::Time.at(epoch)
+      end
+
       def match?(time, tz = nil)
         match_components?(wall_clock(time.to_i, tz))
       end
@@ -184,7 +194,7 @@ module Wurk
       #   * nil          → UTC
       #   * AS::TimeZone → responds to #at
       #   * TZInfo::Tz   → responds to #utc_to_local
-      #   * IANA String  → parsed via ENV TZ override (POSIX `tzset(3)`)
+      #   * IANA String  → resolved via TZInfo (cached; UTC fallback + warning)
       def wall_clock(epoch, tz)
         t = case tz
             when nil then ::Time.at(epoch).utc
@@ -198,15 +208,47 @@ module Wurk
         return tz.at(epoch) if tz.respond_to?(:at) && !tz.is_a?(String)
         return tz.utc_to_local(::Time.at(epoch).utc) if tz.respond_to?(:utc_to_local)
 
-        with_tz_env(tz.to_s) { ::Time.at(epoch) }
-      end
+        zone = self.class.resolve_zone(tz.to_s)
+        zone ? zone.utc_to_local(::Time.at(epoch).utc) : ::Time.at(epoch).utc
+      end
+
+      # IANA String → TZInfo::Timezone, memoized process-wide. Never mutates
+      # ENV['TZ']: ENV is process-global, so the old tzset(3) override leaked
+      # the cron loop's zone into every other thread — processors running user
+      # perform code observed the wrong timezone mid-evaluation (#210). It was
+      # also unreliable: Ruby caches the process zone after first Time use, so
+      # the flip wasn't honored consistently anyway.
+      #
+      # tzinfo is a soft dependency (always present under Rails via
+      # activesupport). A missing gem or unknown identifier caches `false` so
+      # the warning logs once, not once per evaluated minute, and the loop
+      # degrades to UTC instead of crashing the poller.
+      @tz_cache = {}
+      @tz_cache_mutex = ::Mutex.new
+
+      class << self
+        def resolve_zone(name)
+          cached = @tz_cache[name]
+          return cached || nil unless cached.nil?
+
+          @tz_cache_mutex.synchronize do
+            @tz_cache.fetch(name) { @tz_cache[name] = load_zone(name) } || nil
+          end
+        end
 
-      def with_tz_env(name)
-        old = ENV.fetch('TZ', nil)
-        ENV['TZ'] = name
-        yield
-      ensure
-        ENV['TZ'] = old
+        private
+
+        def load_zone(name)
+          require 'tzinfo' unless defined?(::TZInfo)
+          ::TZInfo::Timezone.get(name)
+        rescue ::LoadError
+          Wurk.logger&.warn("[cron] tzinfo gem unavailable — evaluating timezone #{name.inspect} as UTC. " \
+                            'Add `gem "tzinfo"` for timezone-aware cron.')
+          false
+        rescue ::StandardError => e
+          Wurk.logger&.warn("[cron] unknown timezone #{name.inspect} (#{e.class}: #{e.message}) — evaluating as UTC")
+          false
+        end
       end
     end
 

data/lib/wurk/dead_set.rb

@@ -5,11 +5,16 @@ require_relative 'job_set'
 module Wurk
   # Capped ZSET of jobs that exhausted retries (the "morgue"). Bounded by
   # `dead_max_jobs` and `dead_timeout_in_seconds` config knobs — every
-  # `kill` trims both axes. Death handlers fire on retry-exhausted kills
-  # (notify_failure: true), not on user-initiated UI kills.
+  # `kill` trims both axes. Death handlers fire by default — including on
+  # API/UI kills, matching Sidekiq — unless `notify_failure: false`.
   #
   # Spec: docs/target/sidekiq-free.md §19.5, §17.2, §31.8.
   class DeadSet < JobSet
+    # Synthesized as the death-handler exception for kills without a real
+    # error. Byte-for-byte Sidekiq's message — Wurk::Unique::DEATH_HANDLER
+    # matches on it to keep the lock on manual kills (Ent parity), and
+    # ecosystem handlers may pattern-match it too.
+    API_KILL_MESSAGE = 'Job killed by API'
     # Optional `name` allows tests to operate on a namespaced ZSET; production
     # callers always use the default `'dead'` key (wire-compat with Sidekiq).
     def initialize(name = 'dead')
@@ -48,7 +53,7 @@ module Wurk
     def kill(message, opts = {}) # rubocop:disable Naming/PredicateMethod
       notify = opts.fetch(:notify_failure, true)
       do_trim = opts.fetch(:trim, true)
-      ex = opts[:ex] || RuntimeError.new('Job killed')
+      ex = opts[:ex] || RuntimeError.new(API_KILL_MESSAGE).tap { |e| e.set_backtrace(caller) }
 
       now = ::Process.clock_gettime(::Process::CLOCK_REALTIME)
       Wurk.redis { |conn| conn.call('ZADD', @name, now.to_s, message) }

data/lib/wurk/deploy.rb

@@ -24,10 +24,14 @@ module Wurk
     # Sidekiq Pro's LABEL_MAKER so existing deploy hooks keep working.
     LABEL_MAKER = -> { `git log -1 --format="%h %s"`.strip }
 
-    # Class-level shorthand `Wurk::Deploy.mark!(label: "abc")` builds a
-    # one-shot Deploy and delegates. Matches Sidekiq's `Sidekiq::Deploy.mark!`.
-    def self.mark!(label: nil, at: ::Time.now)
-      new.mark!(label: label, at: at)
+    # Class-level shorthand: builds a one-shot Deploy and delegates. Sidekiq's
+    # `Sidekiq::Deploy.mark!` takes a POSITIONAL label (spec §23,
+    # `def self.mark!(label = nil)`) — capistrano-sidekiq and custom deploy
+    # hooks call `Sidekiq::Deploy.mark!("abc123 release")` that way. The `**opts`
+    # also absorbs the `label:` keyword so Wurk's own keyword callers keep
+    # working; positional wins when both are given.
+    def self.mark!(label = nil, at: ::Time.now, **opts)
+      new.mark!(label: label.nil? ? opts[:label] : label, at: at)
     end
 
     def initialize(pool: nil)

data/lib/wurk/encryption.rb

@@ -160,10 +160,15 @@ module Wurk
       # array with the last element replaced by the literal `"<encrypted>"`
       # when the job opted in. Cleartext preceding args are untouched so
       # operators can still triage on user_id / object_id / etc.
+      #
+      # Masks on the `encrypt` flag *or* an envelope-shaped last arg: a stored
+      # job hash doesn't always carry `encrypt` (it's a `sidekiq_options`, not
+      # persisted on every record), so envelope detection is the real guard —
+      # it keeps ciphertext out of the dashboard regardless of the flag.
       def redact_args(job)
         args = job['args'] || job[:args] || []
-        return args unless job['encrypt'] || job[:encrypt]
         return args if args.empty?
+        return args unless job['encrypt'] || job[:encrypt] || envelope?(args.last)
 
         args[0..-2] + ['<encrypted>']
       end