wurk 1.4.0 → 1.5.0

data/lib/wurk/launcher.rb

@@ -11,9 +11,11 @@ require_relative 'leader'
 require_relative 'cron'
 require_relative 'metrics/rollup'
 require_relative 'metrics/queue_rollup'
+require_relative 'metrics/flusher'
 require_relative 'history'
 require_relative 'fetcher/reaper'
 require_relative 'timer_loop'
+require_relative 'shutdown_gate'
 
 module Wurk
   # Top-level supervisor inside each worker process. Owns the Manager pool
@@ -49,7 +51,7 @@ module Wurk
     # shutdown lands right after boot; teardown must not hang on it.
     BOOT_RECLAIM_JOIN_TIMEOUT = 5
 
-    attr_accessor :managers, :poller, :cron_poller, :metrics_rollup, :queue_rollup, :history
+    attr_accessor :managers, :poller, :cron_poller, :metrics_rollup, :queue_rollup, :metrics_flusher, :history
 
     def initialize(config, embedded: false)
       @config = config
@@ -59,31 +61,37 @@ module Wurk
       # beating would never publish quiet=true and would expire out of the live
       # set (#236). Only #stop ends the beat, by terminating @beat_timer.
       @done = false
+      @shutdown_gate = ShutdownGate.new
       @beat_timer = TimerLoop.new(BEAT_PAUSE)
       @managers = build_managers
-      @poller = build_poller
-      @cron_poller = build_cron_poller
-      @metrics_rollup = build_metrics_rollup
-      @queue_rollup = build_queue_rollup
-      @history = build_history
+      build_loops
       @leader = build_leader
       @reaper = build_reaper
-      @started_at = nil
-      @heartbeat = nil
-      @heartbeat_thread = nil
-      @boot_reclaim_thread = nil
       @health_server = build_health_server
+      reset_thread_state
     end
 
     # Boot order matters:
     #   1. freeze! the config so mutations after fork are visible mistakes.
-    #   2. spawn the heartbeat thread BEFORE the managers so the dashboard
-    #      sees the process the moment it can pick up jobs.
-    #   3. start the scheduler poller + the cron poller (both leader-gated for
-    #      what they enqueue; safe to start before leadership is settled since
-    #      a non-leader tick just returns early).
-    #   4. start the managers (which start their processors).
-    #   5. start the health probe server LAST so the listener doesn't
+    #      A swarm child finds the slot-independent half already frozen by its
+    #      parent (Configuration#prepare_for_fork!); what closes here is the
+    #      capsules, which stayed open for this child's slot and pools.
+    #   2. start the managers FIRST. They are the only thing here on the
+    #      time-to-first-job path (the number bench/vs_sidekiq.rb measures);
+    #      everything below is periodic background work whose first tick is
+    #      seconds away, so it has nothing to gain from going ahead of them.
+    #   3. spawn the heartbeat thread, so the dashboard sees the process
+    #      right after it can pick up jobs.
+    #   4. start the reaper and the boot-time reclaim sweep — kill-9 recovery,
+    #      not decoration: a SIGKILLed sibling's in-flight jobs wait on this,
+    #      so it stays ahead of the periodic loops.
+    #   5. start the periodic loops. None of them ticks at zero — TimerLoop#run
+    #      waits an interval before its first yield, Scheduled::Poller waits
+    #      INITIAL_WAIT, and Leader waits DEFAULT_INITIAL_WAIT — so starting
+    #      them last costs a few thread spawns and nothing else. Both leader-
+    #      gated pollers are also safe to start before leadership settles: a
+    #      non-leader tick just returns early.
+    #   6. start the health probe server LAST so the listener doesn't
     #      accept k8s probes until the rest of the launcher is up.
     def run(async_beat: true)
       @started_at = Time.now.to_f
@@ -92,13 +100,13 @@ module Wurk
       # CLI, embedded) runs through here, so none boots with a nil fetcher.
       @config.capsules.each_value(&:prepare!)
       @config.freeze!
-      @heartbeat_thread = safe_thread('heartbeat', &method(:start_heartbeat)) if async_beat
-      [@poller, @leader, @cron_poller, @metrics_rollup, @queue_rollup, @history].compact.each(&:start)
       @managers.each(&:start)
+      @heartbeat_thread = safe_thread('heartbeat', &method(:start_heartbeat)) if async_beat
       @reaper.start
       # Run on a background thread so /ready probe isn't delayed by a large
       # orphan sweep (reaper.reclaim! is atomic, but can scan many entries).
       @boot_reclaim_thread = safe_thread('boot-reclaim', &method(:boot_reclaim))
+      start_periodic_components
       @health_server&.start
     rescue StandardError
       # Boot is not atomic: whatever raised (a health-check port already bound,
@@ -125,20 +133,35 @@ module Wurk
       fire_event(:quiet, reverse: true)
     end
 
-    # Graceful shutdown. Deadline is monotonic so wall-clock skew can't
-    # extend it. Managers stop in parallel threads so a slow capsule
-    # doesn't block its siblings — and each drain is guarded, because a
-    # capsule that blows up mid-drain (Redis down during bulk_requeue) used
-    # to surface out of `join` and skip the whole teardown tail, leaving the
+    # Graceful shutdown, single-shot: several requests can be in flight at once
+    # (a dashboard-queued TERM, the embedded host's own `Embedded#stop`, a
+    # Manager that can no longer hold its concurrency), so the first caller
+    # drains and the rest wait it out — see ShutdownGate. Deadline is monotonic
+    # so wall-clock skew can't extend it. Managers stop in parallel threads so a
+    # slow capsule doesn't block its siblings — and each drain is guarded,
+    # because a capsule that blows up mid-drain (Redis down during bulk_requeue)
+    # used to surface out of `join` and skip the whole teardown tail, leaving the
     # leader lock held, the process listed as live, and its port open.
+    #
+    # The joins get one shared budget of `deadline + TimerLoop::JOIN_TIMEOUT`,
+    # not an open-ended wait. Manager#stop is meant to run a little past the
+    # deadline — on expiry it bulk_requeues the in-flight UnitsOfWork, kills the
+    # threads and gives them a ~3s window to run their `ensure` blocks — but
+    # past that it is wedged (a `fetcher.terminate` / `bulk_requeue` parked on a
+    # Redis that stopped answering), and every further second spent waiting
+    # comes out of the teardown tail below, which the swarm parent only allows
+    # `shutdown_timeout + Swarm::SHUTDOWN_GRACE` for before it SIGKILLs us
+    # mid-drain.
     def stop
-      deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + (@config[:timeout] || 25)
-      quiet
-      stoppers = @managers.map { |m| Thread.new { teardown_step('manager') { m.stop(deadline) } } }
-      fire_event(:shutdown, reverse: true)
-      stoppers.each(&:join)
-    ensure
-      release_components
+      @shutdown_gate.run do
+        deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + (@config[:timeout] || 25)
+        quiet
+        stoppers = @managers.map { |m| Thread.new { teardown_step('manager') { m.stop(deadline) } } }
+        fire_event(:shutdown, reverse: true)
+        @shutdown_gate.join_within(stoppers, deadline + TimerLoop::JOIN_TIMEOUT)
+      ensure
+        release_components
+      end
     end
 
     def stopping?
@@ -200,12 +223,14 @@ module Wurk
       %i[stop_heartbeat clear_heartbeat].each { |step| teardown_step(step) { send(step) } }
       # Unguarded: fire_event already reports and skips past a raising hook.
       fire_event(:exit, reverse: true)
-      # Embedded only: a swarm child or standalone process exits right after
-      # #stop anyway, so disconnecting here would just make every unit test
-      # that inspects Redis post-stop rebuild a pool for no reason. Embedded
-      # hosts (Puma, a rake task) keep running and can `run` again later —
-      # without this a stop-then-run cycle doubles the live socket set.
-      teardown_step('redis-pools') { @config.reset_redis_pools! } if @embedded
+      # Unconditional. A swarm child or standalone process exits right after
+      # #stop, so for those it only closes sockets the kernel was about to close
+      # anyway — but every other driver survives us: an embedded host (Puma, a
+      # rake task) that boots a fresh Launcher later, and anything driving
+      # Launcher directly. Skipping those leaked one main + one fetch pool per
+      # capsule, live, for the life of the host. Idempotent: `reset_redis_pools!`
+      # drops the memo, so the next checkout rebuilds.
+      teardown_step('redis-pools') { @config.reset_redis_pools! }
     ensure
       # In an ensure of its own, not merely a guarded step: a leaked TCPServer
       # FD survives even a non-StandardError unwind (a second TERM landing
@@ -214,11 +239,26 @@ module Wurk
       teardown_step('health-server') { @health_server&.stop }
     end
 
+    # Mirror of #stop_periodic_components: every loop this process runs on a
+    # timer, started in one place at the tail of #run. `compact` because the
+    # history snapshotter is opt-in and an embedded boot may have stripped the
+    # rest.
+    def start_periodic_components
+      [@poller, @leader, @cron_poller, @metrics_rollup,
+       @queue_rollup, @metrics_flusher, @history].compact.each(&:start)
+    end
+
     # Split out of #release_components to keep it under the AbcSize/
-    # CyclomaticComplexity ceilings — these three are the "periodic loop"
-    # releases, independently guarded like everything else in the tail.
+    # CyclomaticComplexity ceilings — these are the "periodic loop" releases,
+    # independently guarded like everything else in the tail.
+    #
+    # The metrics flusher goes first: its #terminate drains the last window of
+    # per-job counters into the `j|…` minute buckets, and Metrics::Rollup reads
+    # exactly those buckets — stopping the rollup first would give its final
+    # tick nothing to roll.
     def stop_periodic_components
-      [@cron_poller, @metrics_rollup, @queue_rollup, @history].each { |t| teardown_step(t.class) { t&.terminate } }
+      [@metrics_flusher, @cron_poller, @metrics_rollup, @queue_rollup,
+       @history].each { |t| teardown_step(t.class) { t&.terminate } }
       teardown_step('reaper') { @reaper&.stop }
       teardown_step('leader') { @leader&.stop }
     end
@@ -335,8 +375,15 @@ module Wurk
     # concurrency. Standalone hands off to the installed TERM trap; embedded
     # owns no traps, so it drains in place — on its own thread, because callers
     # may be a thread `stop` itself joins (the heartbeat) or kills (a Processor).
+    #
+    # That thread is spawned once and retained by the gate: every later request
+    # rides the same drain instead of leaving another unreferenced `stop`
+    # running behind it. Returned so a caller that can afford to wait (a test,
+    # a host teardown) has something to join.
     def request_shutdown
-      @embedded ? Thread.new { stop } : redeliver('TERM')
+      return redeliver('TERM') unless @embedded
+
+      @shutdown_gate.runner { safe_thread('launcher-stop') { stop } }
     end
 
     # Separate method so tests can stub it — really sending TERM/TSTP would
@@ -352,49 +399,46 @@ module Wurk
       @config.capsules.values.map { |cap| Manager.new(cap, shutdown: method(:request_shutdown)) }
     end
 
-    def build_poller
-      Wurk::Scheduled::Poller.new(@config)
-    end
-
-    # Periodic (cron) tick loop. Like the scheduler poller, every process runs
-    # one, but only the elected leader enqueues — the single-leader invariant is
-    # what guarantees exactly one enqueue per (loop, tick) across the cluster.
-    def build_cron_poller
-      Wurk::Cron::Poller.new(@config)
-    end
-
-    # Leader-only metrics rollup. Every process runs one, but only the elected
-    # leader writes the cluster-total time-series buckets the dashboard charts
-    # read — a non-leader tick returns early. Tune the cadence (tests shrink it)
-    # with `config.metrics_rollup_interval`.
-    def build_metrics_rollup
-      Wurk::Metrics::Rollup.new(@config)
-    end
-
-    # Leader-only per-queue gauge sampler. Like the metrics rollup, every
-    # process runs one but only the leader writes the `qm|…` size/latency
-    # buckets the Historical tab's per-queue charts read.
-    def build_queue_rollup
-      Wurk::Metrics::QueueRollup.new(@config)
+    # The periodic loops, built in one place because they are started together
+    # (#run) and released together (#stop_periodic_components). Every process
+    # runs every one of them; what differs is who does the work inside a tick:
+    #
+    #   poller / reaper   every process, work shared through Redis
+    #   cron_poller       leader only enqueues — that is the exactly-once guard
+    #   metrics_rollup    leader only writes the cluster-total chart buckets
+    #                     (cadence: `config.metrics_rollup_interval`)
+    #   queue_rollup      leader only writes the `qm|…` per-queue gauges
+    #   metrics_flusher   NOT leader-gated: the counters it drains exist only in
+    #                     this process's memory, so every process flushes its own
+    #   history           Ent §5 snapshotter, leader-gated, opt-in via
+    #                     `config.retain_history`
+    def build_loops
+      @poller = Wurk::Scheduled::Poller.new(@config)
+      @cron_poller = Wurk::Cron::Poller.new(@config)
+      @metrics_rollup = Wurk::Metrics::Rollup.new(@config)
+      @queue_rollup = Wurk::Metrics::QueueRollup.new(@config)
+      @metrics_flusher = Wurk::Metrics::Flusher.new(@config)
+      @history = Wurk::History.new(@config) if @config.history_enabled?
     end
 
-    # Ent §5 Historical Metrics snapshotter — only when the host opted in via
-    # `config.retain_history`. Leader-gated like the rollups, so just one
-    # process emits the cluster-wide snapshot per interval.
-    def build_history
-      Wurk::History.new(@config) if @config.history_enabled?
+    # Filled in by #run. Declared up front so #initialize reads as the full
+    # inventory of what a Launcher owns.
+    def reset_thread_state
+      @started_at = @heartbeat = @heartbeat_thread = @boot_reclaim_thread = nil
     end
 
     # Every worker process campaigns for the single cluster lock (`dear-leader`);
     # one wins and renews it, the rest follow and promote on its death. Cadence
     # falls back to the spec defaults (TTL 30 / renew 15 / follower 60) unless
-    # the host tunes it. `Leader#start` no-ops under `WURK_LEADER=false`.
+    # the host tunes it, plus the short pre-campaign delay that keeps the first
+    # CAS off the boot path. `Leader#start` no-ops under `WURK_LEADER=false`.
     def build_leader
       Wurk::Leader.new(
         config: @config,
         ttl: @config[:leader_ttl] || Wurk::Leader::DEFAULT_TTL,
         renew_interval: @config[:leader_renew_interval] || Wurk::Leader::DEFAULT_RENEW_INTERVAL,
-        follower_interval: @config[:leader_follower_interval] || Wurk::Leader::DEFAULT_FOLLOWER_INTERVAL
+        follower_interval: @config[:leader_follower_interval] || Wurk::Leader::DEFAULT_FOLLOWER_INTERVAL,
+        initial_wait: @config[:leader_initial_wait] || Wurk::Leader::DEFAULT_INITIAL_WAIT
       )
     end
 

data/lib/wurk/leader.rb

@@ -5,6 +5,7 @@ require 'socket'
 require_relative 'component'
 require_relative 'lua'
 require_relative 'pool_checkout'
+require_relative 'timer_loop'
 
 module Wurk
   # Cluster leader election via Redis `SET NX EX`. Single-leader-per-cluster
@@ -21,9 +22,12 @@ module Wurk
   # too — it is never re-read on subsequent acquires, only on transitions.
   #
   # Cadence per spec: renew every 15s while leader, recheck every 60s as
-  # follower, lock TTL 30s. Opt out a process from campaigning entirely
-  # with `WURK_LEADER=false` (or its Sidekiq alias `SIDEKIQ_LEADER=false`),
-  # useful for hot-standby pools.
+  # follower, lock TTL 30s. The campaign itself starts `initial_wait` seconds
+  # after `#start` — the spec fixes the renew/follower/TTL cadence but says
+  # nothing about when the first campaign runs, and holding it back keeps a
+  # booting process's opening Redis round trips on the job path. Opt out a
+  # process from campaigning entirely with `WURK_LEADER=false` (or its Sidekiq
+  # alias `SIDEKIQ_LEADER=false`), useful for hot-standby pools.
   #
   # Spec: docs/target/sidekiq-ent.md §6.
   class Leader
@@ -32,6 +36,13 @@ module Wurk
     DEFAULT_TTL = 30
     DEFAULT_RENEW_INTERVAL = 15
     DEFAULT_FOLLOWER_INTERVAL = 60
+    # Delay before the campaign's first `SET NX EX`, so a booting process
+    # spends its opening Redis round trips on fetching jobs rather than on a
+    # leadership CAS. Every leader-gated consumer (cron, both rollups,
+    # history) waits out a 30-60s interval before its own first tick, so
+    # nothing observes the gap. Tune with `config[:leader_initial_wait]`;
+    # 0 campaigns immediately.
+    DEFAULT_INITIAL_WAIT = 1
     OPT_OUT_ENV = 'WURK_LEADER'            # native opt-out env
     SIDEKIQ_OPT_OUT_ENV = 'SIDEKIQ_LEADER' # Sidekiq Ent drop-in alias (§6.2/§7.2)
     THREAD_NAME = 'wurk-leader'
@@ -48,12 +59,14 @@ module Wurk
     def initialize(config: nil, key: DEFAULT_KEY, ttl: DEFAULT_TTL, # rubocop:disable Metrics/ParameterLists
                    renew_interval: DEFAULT_RENEW_INTERVAL,
                    follower_interval: DEFAULT_FOLLOWER_INTERVAL,
+                   initial_wait: DEFAULT_INITIAL_WAIT,
                    pool: nil, owner: nil)
       @config = config
       @key = key
       @ttl = ttl
       @renew_interval = renew_interval
       @follower_interval = follower_interval
+      @initial_wait = initial_wait.to_f
       @pool = pool
       @owner = owner || cluster_identity
       @held = false
@@ -136,14 +149,20 @@ module Wurk
       @thread
     end
 
+    # Bounded at TimerLoop::JOIN_TIMEOUT like every other periodic component: a
+    # tick parked on a wedged Redis (the campaign is a `SET NX EX`, so it waits
+    # out the socket timeouts) must not hold the whole process's teardown open —
+    # the swarm parent SIGKILLs a child that overruns its shutdown grace. The
+    # CAS release below runs either way; the loop's own trailing release makes
+    # a straggler's second attempt a no-op. A straggler also stays referenced,
+    # so a restart after a timed-out stop can't campaign twice in parallel.
     def stop
       thread = @mutex.synchronize do
         @done = true
         @sleeper.signal
         @thread
       end
-      thread&.join
-      @mutex.synchronize { @thread = nil }
+      @mutex.synchronize { @thread = nil } if thread.nil? || thread.join(TimerLoop::JOIN_TIMEOUT)
       release
     end
 
@@ -224,6 +243,7 @@ module Wurk
     end
 
     def run_loop
+      wait_initial
       until done?
         tick_once
         wait_next
@@ -231,6 +251,13 @@ module Wurk
       release
     end
 
+    # Same condvar as #wait_next, so a `stop` landing inside the pre-campaign
+    # delay wakes the loop immediately instead of holding shutdown open for a
+    # whole initial_wait.
+    def wait_initial
+      wait_for(@initial_wait) if @initial_wait.positive?
+    end
+
     def tick_once
       acquire
     rescue StandardError => e
@@ -238,7 +265,10 @@ module Wurk
     end
 
     def wait_next
-      interval = @held ? @renew_interval : @follower_interval
+      wait_for(@held ? @renew_interval : @follower_interval)
+    end
+
+    def wait_for(interval)
       @mutex.synchronize { @sleeper.wait(@mutex, interval) unless @done }
     end
 

data/lib/wurk/logger.rb

@@ -28,7 +28,7 @@ module Wurk
         }.freeze
 
         def tid
-          Thread.current[:wurk_tid] ||= (Thread.current.object_id ^ ::Process.pid).to_s(36)
+          Wurk::Component.tid
         end
 
         def format_context(ctxt = Wurk::Context.current)

data/lib/wurk/lua/loader.rb

@@ -23,9 +23,15 @@ module Wurk
         # connection errors are the pool wrapper's job (Wurk::RedisPool#with);
         # this only ships the loads.
         def script_load_all(redis)
-          redis.pipelined do |pipe|
-            SCRIPTS.each_value { |src| pipe.call('SCRIPT', 'LOAD', src) }
-          end
+          redis.pipelined { |pipe| queue_script_loads(pipe) }
+        end
+
+        # The same loads, queued onto a pipeline the caller already owns, for a
+        # caller with other work to batch with them: ChildBoot pairs them with
+        # its liveness PING so a child's whole Redis validation costs one round
+        # trip instead of two, on the boot-critical path.
+        def queue_script_loads(pipe)
+          SCRIPTS.each_value { |src| pipe.call('SCRIPT', 'LOAD', src) }
         end
 
         # @param redis [RedisClient] a single connection (not a pool)

data/lib/wurk/metrics/accumulator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Wurk
+  module Metrics
+    # The in-memory half of Wurk::Metrics::History. Every execution folds into a
+    # `{pool => {minute => {class => [processed, failed, ms]}}}` tree under one
+    # mutex; Wurk::Metrics::Flusher drains it into Redis on a timer. `HINCRBY`
+    # is additive, so N folded executions leave Redis in the same state as the N
+    # individual pipelines the hot path used to send.
+    #
+    # Knows nothing about Redis — History owns the write, this owns the counts.
+    #
+    # The minute is the bucket the job *ran* in, decided by the caller at record
+    # time. That is what keeps the batching a visibility lag instead of a
+    # misattribution: a job that runs at 12:03:59 and flushes at 12:04:02 still
+    # counts toward 12:03. Signed off in
+    # docs/plans/2026/08/06/101-faster-than-sidekiq/00-semantics-signoff.md §2.
+    #
+    # Keyed by the pool the recording middleware handed us (nil = the process
+    # default), so a multi-capsule process flushes each capsule's counts through
+    # the pool that capsule's jobs ran on.
+    class Accumulator
+      # Ceiling on minute buckets retained per pool. Only reachable through
+      # #merge_back: a flush that keeps failing puts its counts back every tick,
+      # and a Redis outage that outlives the process would otherwise grow a
+      # structure fed by the job hot path without bound. The newest buckets win
+      # — they are the ones the dashboard is still drawing — and the oldest are
+      # dropped, which these counters have always been allowed to do (a Redis
+      # failure during a metrics write has never changed a job's outcome).
+      MAX_RETAINED_MINUTES = 60
+
+      def initialize
+        @lock = ::Mutex.new
+        @pools = {}
+      end
+
+      # Hot path. Three hash lookups under the mutex; allocates only the first
+      # time a (pool, minute, class) triple is seen.
+      def add(pool, klass, minute, ms, success)
+        @lock.synchronize do
+          counts = (((@pools[pool] ||= {})[minute] ||= {})[klass] ||= [0, 0, 0])
+          counts[success ? 0 : 1] += 1
+          counts[2] += ms
+        end
+      end
+
+      # Hands the whole tree over and starts a fresh one, so recording never
+      # blocks behind the flush's Redis round trip.
+      def drain
+        @lock.synchronize do
+          drained = @pools
+          @pools = {}
+          drained
+        end
+      end
+
+      # Puts one pool's counts back after its write failed, so the next tick
+      # retries them instead of dropping the window. Merged rather than
+      # assigned: jobs kept recording into the fresh tree while the flush was in
+      # flight, and those counts have not been written yet either.
+      def merge_back(pool, minutes)
+        @lock.synchronize do
+          into = (@pools[pool] ||= {})
+          minutes.each { |minute, classes| merge_minute(into, minute, classes) }
+          trim(into)
+        end
+      end
+
+      def empty?
+        @lock.synchronize { @pools.empty? }
+      end
+
+      private
+
+      def merge_minute(into, minute, classes)
+        target = (into[minute] ||= {})
+        classes.each do |klass, counts|
+          existing = target[klass]
+          if existing
+            counts.each_with_index { |count, i| existing[i] += count }
+          else
+            target[klass] = counts
+          end
+        end
+      end
+
+      def trim(minutes)
+        excess = minutes.size - MAX_RETAINED_MINUTES
+        return if excess <= 0
+
+        minutes.keys.min(excess).each { |minute| minutes.delete(minute) }
+      end
+    end
+  end
+end

data/lib/wurk/metrics/flusher.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../component'
+require_relative '../timer_loop'
+require_relative 'history'
+
+module Wurk
+  module Metrics
+    # Drains Wurk::Metrics::History's in-process accumulator into Redis every
+    # `History::FLUSH_INTERVAL` seconds.
+    #
+    # Deliberately NOT leader-gated, unlike every other periodic component here
+    # (Metrics::Rollup, Metrics::QueueRollup, Wurk::History). Those publish
+    # *cluster* state that one process should own; this publishes counters that
+    # only exist inside this process's memory and that no other process can
+    # write. A leader gate would strand every follower's metrics until it died.
+    #
+    # One tick per process, not per capsule: the accumulator is process-wide and
+    # already keyed by the pool each capsule's jobs recorded through.
+    class Flusher
+      include Component
+
+      # `accumulator` is a collaborator, not an option: every real boot flushes
+      # the process-wide one. Tests inject their own so a broken pool stays
+      # inside the test that built it.
+      def initialize(config, accumulator: History::ACCUMULATOR)
+        @config = config
+        @accumulator = accumulator
+        @timer = TimerLoop.new(History::FLUSH_INTERVAL)
+        @thread = nil
+      end
+
+      def start
+        return @thread if @thread
+
+        @timer.reset
+        @thread = safe_thread('metrics-flush') { @timer.run { tick } }
+      end
+
+      # Flushes once more in an `ensure`: this stops the only thread that would
+      # have written the window accumulated since the last tick, so without it a
+      # graceful shutdown would drop up to FLUSH_INTERVAL of counters — the cost
+      # the sign-off accepts for a *hard* kill only.
+      #
+      # Launcher#stop joins the manager drains before the teardown tail reaches
+      # us, so by the time this runs no job is still recording.
+      #
+      # Cleared only on a confirmed join (Thread#join returns nil on timeout): a
+      # wedged thread must stay tracked so #start's guard returns it instead of
+      # calling @timer.reset, which would un-terminate the loop it is still
+      # inside and leave two threads draining the same accumulator.
+      def terminate
+        @timer.terminate
+        @thread = nil if @thread&.join(TimerLoop::JOIN_TIMEOUT)
+      ensure
+        tick
+      end
+
+      # Never raises: this runs on a `safe_thread`, whose watchdog re-raises
+      # after reporting, and a reported-then-dead flusher would silently stop
+      # every counter in the process for a blip Redis recovers from. The
+      # accumulator has already merged the failed window back for the next tick.
+      def tick
+        History.flush(@accumulator)
+      rescue StandardError => e
+        handle_exception(e, { context: 'metrics-flush' })
+      end
+    end
+  end
+end