pgbus 0.18.2 → 0.19.1

data/README.md

@@ -139,6 +139,8 @@ The capsule string DSL is the shortest form for the common case. Use `c.capsule`
 
 Configuration is validated eagerly: `Pgbus.configure` runs `Configuration#validate!` right after your block yields, so an invalid value (`visibility_timeout = 0`, for example) raises `Pgbus::ConfigurationError` at boot instead of failing later inside a worker. Set `c.eager_validation = false` for the rare setup that intentionally holds a transiently-invalid config across sequential `configure` calls.
 
+Configuration is finalized at boot: once the app's initializers have run, the engine calls `Pgbus.finalize!`, which freezes every plain-data setting (strings, symbols, numbers, regexps, and arrays and hashes of those) into a Ractor-shareable value. Callables and the logger are left as they are. Setters keep working, and a later `Pgbus.configure` finalizes again, but changing a collection in place after boot (`Pgbus.configuration.streams_durable_patterns << "x"`) raises `FrozenError`: assign a new value instead. `c.error_reporters << reporter` keeps working. Without Rails, each `Pgbus.configure` finalizes at its end; `pgbus start` finalizes again once its flags are applied. Call `Pgbus.finalize!` yourself only when you configure pgbus through setters alone. A value that cannot be made shareable (a lambda that closes over app state, a logger, a filter list holding a proc) never makes finalizing raise: it is kept as it is, for the main Ractor. More in [docs/concurrency.md](docs/concurrency.md).
+
 > **Upgrading from an older pgbus?** Run `rails generate pgbus:update`. It inspects your live database and adds any missing pgbus migrations to `db/migrate` (or `db/pgbus_migrate` if you use `connects_to`). The generator detects your separate-database config automatically from `Pgbus.configuration.connects_to` or by scanning the initializer / `config/application.rb`, so you don't have to re-specify `--database=pgbus` every time.
 >
 > Useful flags: `--dry-run` (print the plan without creating files), `--skip-migrations`, `--quiet`. Running it on a database with no pgbus tables at all will redirect you to `pgbus:install` instead of stacking individual add_* migrations.
@@ -691,6 +693,8 @@ end
 
 **Not recommended for:** CPU-bound jobs (image processing, heavy computation). These block the single reactor thread and should use thread mode.
 
+Which state is fiber-local (broadcast options, the batch a job joins, the uniqueness key an enqueue holds) and what that means when work hops between fibers is in [docs/concurrency.md](docs/concurrency.md), with the threads each process runs and pgbus's Ractor readiness.
+
 ## Routing and ordering
 
 How messages flow between producers and the workers that handle them: priority sub-queues, consumer priority for active/standby workers, and single-active-consumer for strict ordering.
@@ -1213,6 +1217,7 @@ All tools are read-only — no tool mutates state, and there is no raw-SQL passt
 | `pgbus_dlq` / `pgbus_dlq_detail` | Dead-letter inspection. Paginated. |
 | `pgbus_locks` | Active uniqueness locks (the leaked-lock diagnostic). Paginated (`page`, `per_page` max 100; returns `total`, capped at 10,000, and `has_more`). |
 | `pgbus_throughput` / `pgbus_stats` | Recent throughput time series and status counts. |
+| `pgbus_deploy_tasks` | Deploy tasks, their state and the rollover status (read-only). |
 | `pgbus_recurring` | Recurring task schedule + last/next run times. All tasks unless `page` / `per_page` is given (then `total` is capped at 10,000); returns `total`, `has_more`. |
 
 #### Security
@@ -2212,6 +2217,42 @@ pgbus start --workers-only --capsule default
 
 The capsule name is the `:name` you passed to `c.capsule` in your initializer (or the first queue token when using the string DSL).
 
+### Deploy tasks
+
+One-time work owed by a release (a backfill, a data fix, a cache warm). A deploy task runs once per `(key, version)`, only after every live pgbus process reports the new app revision and at least one worker on that revision is alive. A scheduled run never happens on old code during the deploy overlap window (Run now, below, is deliberately ungated), two schedulers (multi-host, overlap) never both fire it, and an owed task is not forgotten. It is not exactly-once: a failure between the enqueue and recording the run can repeat it after a restart, so keep deploy tasks idempotent.
+
+```yaml
+# config/deploy_tasks.yml
+production:
+  backfill_order_totals:
+    class: BackfillOrderTotalsJob      # or command: "Orders.backfill_totals!"
+    version: 2                          # bump to run again after the next rollover (default 1)
+    queue: maintenance
+    args: [{ batch_size: 500 }]
+    description: Recompute totals after the currency migration
+  warm_fragment_caches:
+    command: "FragmentCacheWarmer.run"
+    every_deploy: true                  # runs after every rollover, dedup'd on the app revision
+```
+
+The file has the shape of `config/recurring.yml` minus `schedule:`, plus `version:` and `every_deploy:`. It is environment-scoped or flat, ERB is allowed, and `config.deploy_tasks_files` lists several files (explicit files replace the default). A task is a `class:` (an ActiveJob class; anything else is skipped with a warning at scheduler boot) or a `command:` (`Const.method`, run by `Pgbus::Recurring::CommandJob`), with optional `queue`, `args`, `priority` and `description`.
+
+- **`version:`** (default `"1"`, compared as a string): bump it in the same commit as a new data fix to run the task again after that deploy.
+- **`every_deploy: true`**: runs after every rollover, dedup'd on the revision, so a rollback deploy re-fires it and a scheduler crash-restart does not. `version` is ignored (a warning is logged).
+- **Revision**, first non-blank wins: `config.app_revision` (a String or a callable) → `ENV["PGBUS_REVISION"]` → `ENV["DASH_VERSION"]` → `ENV["KAMAL_VERSION"]` → the `REVISION` file in `Rails.root` (Capistrano). dash and Kamal need no configuration. Every pgbus process stamps it into its heartbeat row (`metadata["revision"]`, shown in the Processes page's expanded row). Without a revision the gate stays closed: tasks wait, the scheduler warns once at boot, and only Run now enqueues.
+- **The gate** (checked by the scheduler at most every 5 s): live processes are those with a heartbeat in the last 5 minutes. It is closed while any live process reports another revision (a process with no revision, such as a pre-upgrade pgbus, counts as lagging) or while no live worker runs the new revision. A gracefully stopped process deletes its row at once, so a clean dash/Kamal deploy opens the gate within a scheduler tick after the last old container drains; a hard-killed old container keeps it closed until its row goes stale (5 minutes).
+- **Who runs it**: the scheduler that runs recurring tasks. The supervisor forks it when recurring or deploy tasks are configured (`config.deploy_tasks_enabled`, default `true`); `--scheduler-only` works as before. At boot it syncs the declared tasks into `pgbus_deploy_tasks` and arms the owed ones. A compare-and-set claim on the row means two schedulers never both fire.
+- **"Ran" means enqueued**, like recurring: the task goes through ActiveJob `perform_later`, so uniqueness, batches, concurrency, priority, retries and the DLQ apply, and the outcome is on the Jobs page. A failed enqueue re-arms the task, logs it, reports it to the error reporters and retries after 5 s, doubling up to 5 minutes (Disable the task to stop it). The run row marks a version as done: if it cannot be written right after a successful enqueue, the next scheduler boot runs the task again, so keep deploy tasks idempotent. Due tasks are enqueued in key order with no completion ordering between them.
+- **Dashboard**: the "Deploy tasks" page (`/pgbus/deploy_tasks`, plus a show page per task with its configuration and last 25 runs) shows whether the fleet has rolled over to the scheduler's revision, with live process counts per revision, and each task as ran, waiting (and why), due, disabled or never ran. **Run now** enqueues immediately, with no gate and no claim, and records a manual run; it does not cancel a pending rollover run (Disable the task for that). **Enable/Disable** is honoured on every tick.
+- **History**: `pgbus_deploy_task_runs`, kept for `config.deploy_task_run_retention` (default 90 days, `nil` keeps forever); the dispatcher prunes hourly. Each enqueue emits `pgbus.deploy_task.enqueue` (`task`, `version`, `revision`, `triggered_by`).
+
+```bash
+rails generate pgbus:add_deploy_tasks                  # migration + config/deploy_tasks.yml
+rails generate pgbus:add_deploy_tasks --database=pgbus # for a separate database
+```
+
+`rails generate pgbus:update` detects the missing tables; fresh installs (`pgbus:install`) already have them.
+
 ### Dashboard
 
 The dashboard is a mountable Rails engine at `/pgbus` with:
@@ -2286,6 +2327,8 @@ Pgbus uses these tables (created via PGMQ and migrations):
 | `pgbus_outbox_entries` | Transactional outbox entries pending publication |
 | `pgbus_recurring_tasks` | Recurring job definitions |
 | `pgbus_recurring_executions` | Recurring job execution history |
+| `pgbus_deploy_tasks` | Declared deploy tasks, their arm (`armed_at`/`armed_for`) and `enabled` flag |
+| `pgbus_deploy_task_runs` | Deploy task run history (task_key, version, revision, triggered_by, queue_name, msg_id, run_at) |
 | `pgbus_presence_members` | Stream presence tracking (who is subscribed) |
 | `pgbus_stream_stats` | Stream broadcast/connect/disconnect metrics (opt-in) |
 
@@ -2369,6 +2412,7 @@ Curated headline options for the README. The full operator reference (with types
 | `zombie_detection` | `true` | Detect and reclaim work from crashed workers |
 | `read_timeout` | `30` | Seconds before a single PGMQ read is bounded (libpq `statement_timeout` + `tcp_user_timeout` on a dedicated connection; nil disables) |
 | `drain_timeout` | `30` | Seconds to wait for in-flight jobs during graceful shutdown before abandoning them |
+| `immediate_shutdown_grace` | `2` | On QUIT, seconds a worker or consumer gives running jobs to finish before killing them; killed jobs' ActiveRecord connections are reclaimed |
 | `shutdown_timeout` | `drain_timeout + 5` | Seconds the supervisor waits for children after TERM before SIGKILL; an orchestrator's stop grace period must exceed it |
 | `stall_threshold` | `300` | Seconds without progress before a worker is considered stalled |
 | `priority_levels` | `nil` | Number of priority sub-queues (nil = disabled, 2-10) |
@@ -2383,6 +2427,11 @@ Curated headline options for the README. The full operator reference (with types
 | `outbox_batch_size` | `100` | Max entries per outbox poll cycle |
 | `outbox_retention` | `1.day` | How long to keep published outbox entries. Accepts seconds, Duration, or `nil` to disable cleanup |
 | `idempotency_ttl` | `7.days` | How long to keep processed event records. Accepts seconds, Duration, or `nil` to disable cleanup |
+| `app_revision` | `nil` | App revision for deploy tasks: a String or a callable returning one. Falls back to `PGBUS_REVISION`, `DASH_VERSION`, `KAMAL_VERSION`, then the `REVISION` file |
+| `deploy_tasks` | `nil` | Hash of deploy tasks, same shape as `config/deploy_tasks.yml` |
+| `deploy_tasks_files` | `nil` | Array of deploy-task YAML files (replaces the default `config/deploy_tasks.yml`) |
+| `deploy_tasks_enabled` | `true` | Fork the scheduler for deploy tasks; set `false` to turn them off |
+| `deploy_task_run_retention` | `90.days` | How long to keep deploy task run history. Accepts seconds, Duration, or `nil` to keep forever |
 | `allowed_global_id_models` | `nil` | Allowlist of Class/Module models permitted as GlobalID **job arguments** and EventBus payloads. `nil` = allow-all (default). `[]` = deny-all. Apps with ActiveStorage should include `ActiveStorage::Blob` (and related models). |
 | `base_controller_class` | `"::ActionController::Base"` | Base class for dashboard controllers (string, constantized at load time) |
 | `return_to_app_url` | `nil` | URL for "back to app" button in dashboard nav (nil hides the button) |

data/app/controllers/pgbus/deploy_tasks_controller.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class DeployTasksController < ApplicationController
+    def index
+      @page = page_param
+      @per_page = per_page
+      @deploy_tasks = data_source.deploy_tasks(page: @page, per_page: @per_page)
+      @deploy_tasks_count = data_source.list_count(:deploy_tasks)
+      @rollover = data_source.deploy_rollover
+      render_frame("pgbus/deploy_tasks/tasks_table") if params[:frame] == "deploy_tasks"
+    end
+
+    def show
+      @task = data_source.deploy_task(params[:id])
+      return redirect_to pgbus.deploy_tasks_path, alert: t("pgbus.deploy_tasks.not_found") unless @task
+
+      @rollover = data_source.deploy_rollover
+    end
+
+    def toggle
+      result = data_source.toggle_deploy_task(params[:id])
+      if result
+        redirect_to pgbus.deploy_tasks_path, notice: t("pgbus.deploy_tasks.toggle.#{result}")
+      else
+        redirect_to pgbus.deploy_tasks_path, alert: t("pgbus.deploy_tasks.toggle.failed")
+      end
+    end
+
+    def enqueue
+      if data_source.enqueue_deploy_task_now(params[:id]) == :enqueued
+        redirect_to pgbus.deploy_tasks_path, notice: t("pgbus.deploy_tasks.enqueue.enqueued")
+      else
+        redirect_to pgbus.deploy_tasks_path, alert: t("pgbus.deploy_tasks.enqueue.failed")
+      end
+    end
+  end
+end

data/app/controllers/pgbus/frontends_controller.rb

@@ -5,27 +5,29 @@ module Pgbus
     protect_from_forgery with: :exception
     skip_after_action :verify_same_origin_request, raise: false
 
-    FRONTEND_ROOT = Engine.root.join("app", "frontend", "pgbus")
+    FRONTEND_ROOT = Engine.root.join("app", "frontend", "pgbus").freeze
 
     STATIC_ASSETS = {
       css: {
-        style: FRONTEND_ROOT.join("style.css")
-      }
+        style: FRONTEND_ROOT.join("style.css").freeze
+      }.freeze
     }.freeze
 
     # Modules are served minified (rake frontend:js), each with its .min.js.map
     # beside it. ApexCharts ships minified already; charts.js imports it on
     # demand, so only Insights downloads it.
     MODULE_OVERRIDES = {
-      application: FRONTEND_ROOT.join("application.min.js"),
-      turbo: FRONTEND_ROOT.join("vendor", "turbo.min.js"),
-      apexcharts: FRONTEND_ROOT.join("vendor", "apexcharts.js")
+      application: FRONTEND_ROOT.join("application.min.js").freeze,
+      turbo: FRONTEND_ROOT.join("vendor", "turbo.min.js").freeze,
+      apexcharts: FRONTEND_ROOT.join("vendor", "apexcharts.js").freeze
     }.freeze
 
+    # An idempotent memo: concurrent first requests glob the same files and
+    # build equal Hashes; whichever is stored, every reader gets a frozen one.
     def self.js_modules
-      @js_modules ||= FRONTEND_ROOT.join("modules").glob("*.min.js").sort
+      @js_modules ||= FRONTEND_ROOT.join("modules").glob("*.min.js").sort # rubocop:disable ThreadSafety/ClassInstanceVariable
                                    .to_h { |f| [f.basename(".min.js").to_s.to_sym, f] }
-                                   .merge(MODULE_OVERRIDES)
+                                   .merge(MODULE_OVERRIDES).freeze
     end
 
     CURRENT_VERSION = Pgbus::VERSION.tr(".", "-").freeze

data/app/helpers/pgbus/application_helper.rb

@@ -94,10 +94,11 @@ module Pgbus
     end
 
     BATCH_BADGE_BASE = "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium"
+    # Interpolated strings are not frozen by the magic comment: freeze each.
     BATCH_BADGE_CSS = {
-      "finished" => "#{BATCH_BADGE_BASE} bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400",
-      "processing" => "#{BATCH_BADGE_BASE} bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400",
-      "pending" => "#{BATCH_BADGE_BASE} bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400"
+      "finished" => "#{BATCH_BADGE_BASE} bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400".freeze,
+      "processing" => "#{BATCH_BADGE_BASE} bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400".freeze,
+      "pending" => "#{BATCH_BADGE_BASE} bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400".freeze
     }.freeze
 
     def pgbus_batch_status_badge(status)

data/app/helpers/pgbus/deploy_tasks_helper.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # The Deploy tasks page's words (issue #536): DeployTaskState results and
+  # the rollover banner as badges and sentences. Moments go through
+  # pgbus_time; the _html keys let the <time> and <code> through, translate
+  # escapes every other argument.
+  module DeployTasksHelper
+    BANNER_TONE_CSS = {
+      green: "bg-green-50 text-green-800 ring-green-200 dark:bg-green-900/30 dark:text-green-200 dark:ring-green-800",
+      yellow: "bg-yellow-50 text-yellow-800 ring-yellow-200 dark:bg-yellow-900/30 dark:text-yellow-200 dark:ring-yellow-800",
+      red: "bg-red-50 text-red-800 ring-red-200 dark:bg-red-900/30 dark:text-red-200 dark:ring-red-800",
+      gray: "bg-gray-50 text-gray-700 ring-gray-200 dark:bg-gray-900/40 dark:text-gray-200 dark:ring-gray-700"
+    }.freeze
+
+    def pgbus_deploy_state_badge(result)
+      tag.span(t("pgbus.deploy_tasks.states.#{result.state}"),
+               class: "#{ApplicationHelper::BATCH_BADGE_BASE} #{ApplicationHelper::JOB_STATE_BADGE_CSS[result.badge_tone]}")
+    end
+
+    # "Waiting for rollover: 2 processes are not on abc123 yet. · ran 1m ago (manual)"
+    def pgbus_deploy_task_reason(result)
+      reason = translate("pgbus.deploy_tasks.reasons.#{result.reason_key}_html", **pgbus_reason_args(result.reason_args))
+      return reason unless result.manual_args
+
+      safe_join([reason, " ", translate("pgbus.deploy_tasks.reasons.manual_html", **pgbus_reason_args(result.manual_args))])
+    end
+
+    def pgbus_deploy_rollover_key(rollover)
+      return "unavailable" unless rollover
+      return "no_scheduler" unless rollover[:scheduler]
+
+      rollover[:reason].to_s
+    end
+
+    def pgbus_deploy_rollover_tone(rollover)
+      case pgbus_deploy_rollover_key(rollover)
+      when "ready" then :green
+      when "no_scheduler", "unavailable" then :red
+      when "no_revision" then :gray
+      else :yellow
+      end
+    end
+
+    def pgbus_deploy_rollover_sentence(rollover)
+      key = pgbus_deploy_rollover_key(rollover)
+      args = { revision: rollover&.dig(:revision) }
+      args[:count] = rollover[:lagging].size if key == "lagging"
+      translate("pgbus.deploy_tasks.banner.#{key}_html", **args)
+    end
+
+    def pgbus_deploy_lagging_process(process)
+      t("pgbus.deploy_tasks.banner.lagging_process",
+        kind: process[:kind], hostname: process[:hostname], pid: process[:pid],
+        revision: process[:revision] || t("pgbus.deploy_tasks.banner.no_revision_label"))
+    end
+
+    # "6 on 8d41b07 · 2 on 3f2a9c1", the most common revision first.
+    def pgbus_deploy_live_counts(rollover)
+      counts = rollover&.dig(:live_by_revision) || {}
+      parts = counts.sort_by { |revision, count| [-count, revision.to_s] }.map do |revision, count|
+        t("pgbus.deploy_tasks.banner.live_count", count: count,
+                                                  revision: revision || t("pgbus.deploy_tasks.banner.no_revision_label"))
+      end
+      safe_join(parts, ProcessesHelper::PART_SEPARATOR)
+    end
+
+    def pgbus_deploy_version(task)
+      task[:every_deploy] ? t("pgbus.deploy_tasks.every_deploy") : t("pgbus.deploy_tasks.version", version: task[:version])
+    end
+
+    # The newer of the last rollover and the last manual run.
+    def pgbus_deploy_last_run(task)
+      [task[:last_rollover_run], task[:last_manual_run]].compact.max_by { |run| Web::JobState.time(run[:run_at]).to_f }
+    end
+  end
+end

data/app/helpers/pgbus/processes_helper.rb

@@ -51,7 +51,7 @@ module Pgbus
     def pgbus_process_raw_metadata(metadata)
       return {} unless metadata.is_a?(Hash)
 
-      metadata.reject { |k, _| RENDERED_METADATA_KEYS.include?(k.to_s) }
+      metadata.reject { |k, v| v.nil? || RENDERED_METADATA_KEYS.include?(k.to_s) }
     end
 
     private

data/app/models/pgbus/deploy_task.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # A declared deploy task and its pending arm (issue #536). armed_at/armed_for
+  # is a row-level compare-and-set: sync arms an owed task, the scheduler's
+  # claim! clears the arm before it enqueues, and a failed enqueue re-arms it.
+  class DeployTask < BusRecord
+    self.table_name = "pgbus_deploy_tasks"
+
+    validates :key, presence: true, uniqueness: true
+    validates :version, presence: true
+
+    scope :static_tasks, -> { where(static: true) }
+    scope :enabled, -> { where(enabled: true) }
+    scope :armed, -> { where.not(armed_at: nil) }
+
+    # Any enabled task waiting to fire: the runner's cheap per-tick check.
+    def self.pending?
+      enabled.armed.exists?
+    end
+
+    # Upserts every declared task (valid Deploy::Task objects) and arms the
+    # owed ones, then removes static rows no longer declared. Never disarms
+    # and never touches enabled; an arm already held keeps its armed_at and
+    # takes the new armed_for (a later bump supersedes an unfired one).
+    def self.sync_from_config!(tasks, revision:, now: Time.current)
+      transaction do
+        tasks.each { |task| sync_task!(task, revision: revision, now: now) }
+        static_tasks.where.not(key: tasks.map(&:key)).delete_all
+      end
+    end
+
+    # Owed-ness comes from the rollover runs, never from the stored row: any
+    # scheduler that boots syncs, including an old-revision one.
+    def self.owed?(task, revision)
+      return !DeployTaskRun.rollover_run_for?(task.key, task.version) unless task.every_deploy
+      return false if revision.nil?
+
+      DeployTaskRun.last_rollover_for(task.key)&.revision != revision
+    end
+
+    def self.sync_task!(task, revision:, now:)
+      record = find_or_initialize_by(key: task.key)
+      record.assign_attributes(
+        class_name: task.class_name, command: task.command, arguments: JSON.generate(task.arguments),
+        queue_name: task.queue_name, priority: task.priority, version: task.version,
+        every_deploy: task.every_deploy, description: task.description, static: true
+      )
+      if owed?(task, revision)
+        record.armed_at ||= now
+        record.armed_for = task.armed_for(revision)
+      end
+      record.save!
+    end
+    private_class_method :sync_task!
+
+    # true when this caller took the arm; false when another scheduler took
+    # it first or the arm is for another version or revision.
+    def claim!(armed_for:, now: Time.current) # rubocop:disable Naming/PredicateMethod -- compare-and-set that reports whether it won
+      self.class.armed.where(id: id, armed_for: armed_for).update_all(armed_at: nil, updated_at: now) == 1
+    end
+
+    # Re-stamps a held arm for +armed_for+, if it is still armed for what
+    # this row was read with. The runner does this when its gate is open on
+    # its own revision and its own version is owed: the other arm belongs to
+    # code no live process runs.
+    def take_over!(armed_for:, now: Time.current) # rubocop:disable Naming/PredicateMethod -- compare-and-set, like #claim!
+      self.class.armed.where(id: id, armed_for: self.armed_for).update_all(armed_for: armed_for, updated_at: now) == 1
+    end
+
+    # Restores this caller's claimed arm after a failed enqueue. Compare-and-set:
+    # only while the arm is still cleared and still for +armed_for+, so a
+    # failed enqueue never overwrites an arm another scheduler set meanwhile.
+    def rearm!(armed_for:, now: Time.current)
+      self.class.where(id: id, armed_at: nil, armed_for: armed_for).update_all(armed_at: now, updated_at: now)
+    end
+
+    def armed?
+      !armed_at.nil?
+    end
+
+    # For display: a corrupt value shows as no arguments.
+    def parsed_arguments
+      decoded_arguments
+    rescue JSON::ParserError
+      []
+    end
+
+    # For Run now: a corrupt value raises (the enqueue reports :failed and
+    # logs it) rather than running the job without its arguments.
+    def to_task
+      Deploy::Task.new(
+        key: key, class_name: class_name, command: command, version: version, every_deploy: every_deploy,
+        queue_name: queue_name, arguments: decoded_arguments, priority: priority, description: description
+      )
+    end
+
+    private
+
+    def decoded_arguments
+      arguments.blank? ? [] : Array(JSON.parse(arguments))
+    end
+  end
+end

data/app/models/pgbus/deploy_task_run.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # One enqueue of a deploy task (issue #536): by the scheduler after a
+  # rollover, or by "Run now" on the dashboard. Rollover runs are what
+  # DeployTask.owed? reads; manual runs never satisfy an obligation.
+  class DeployTaskRun < BusRecord
+    self.table_name = "pgbus_deploy_task_runs"
+
+    ROLLOVER = "rollover"
+    MANUAL = "manual"
+
+    validates :task_key, :version, :triggered_by, :run_at, presence: true
+
+    scope :for_task, ->(key) { where(task_key: key) }
+    scope :rollover, -> { where(triggered_by: ROLLOVER) }
+    scope :manual, -> { where(triggered_by: MANUAL) }
+    scope :recent, ->(limit = 25) { order(id: :desc).limit(limit) }
+    scope :older_than, ->(time) { where(run_at: ...time) }
+
+    # Runs the dispatcher may prune: older than +time+, except the newest
+    # rollover run per (task_key, version). That run is what marks a version
+    # done (DeployTask.owed?); pruning it would re-arm the task on the next
+    # scheduler boot and run it again.
+    def self.prunable_before(time)
+      older_than(time).where.not(id: rollover.group(:task_key, :version).select("MAX(id)"))
+    end
+
+    def self.last_rollover_for(key)
+      rollover.for_task(key).order(id: :desc).first
+    end
+
+    # The newest run per (task_key, triggered_by) for +keys+: the dashboard's
+    # "last rollover run" and "last manual run" columns, in one query.
+    def self.latest_for(keys)
+      where(task_key: keys)
+        .select("DISTINCT ON (task_key, triggered_by) #{quoted_table_name}.*")
+        .order(:task_key, :triggered_by, id: :desc)
+    end
+
+    def self.rollover_run_for?(key, version)
+      rollover.for_task(key).exists?(version: version.to_s)
+    end
+  end
+end

data/app/models/pgbus/job_stat.rb

@@ -37,6 +37,9 @@ module Pgbus
     # false on the first hiccup would permanently disable job stats
     # for the process lifetime, which is a worse failure mode than
     # a few retries. See issue #98 / PR #91 (StreamStat fix).
+    # An idempotent schema memo: concurrent first callers probe the same
+    # schema and store the same Boolean, so the unlocked read/write is safe.
+    # rubocop:disable ThreadSafety/ClassInstanceVariable
     def self.table_exists?
       return @table_exists if defined?(@table_exists)
 
@@ -59,6 +62,7 @@ module Pgbus
       Pgbus.logger.debug { "[Pgbus] Failed to check job stat latency columns: #{e.message}" }
       false
     end
+    # rubocop:enable ThreadSafety/ClassInstanceVariable
 
     # Throughput: jobs per minute bucketed by minute for the last N minutes
     def self.throughput(minutes: 60)

data/app/models/pgbus/processed_event.rb

@@ -21,7 +21,9 @@ module Pgbus
       # failure path leaves the message for VT redelivery — and the next
       # delivery probes again.
       def completion_column?
-        detected = @completion_column
+        # Double-checked: the unlocked read only skips the lock once the
+        # answer is set; it is written under @completion_column_mutex.
+        detected = @completion_column # rubocop:disable ThreadSafety/ClassInstanceVariable
         return detected unless detected.nil?
 
         @completion_column_mutex.synchronize do

data/app/models/pgbus/stream_queue.rb

@@ -30,6 +30,15 @@ module Pgbus
     # unsynchronized check-and-set could WARN more than once per process.
     @record_failure_mutex = Mutex.new
 
+    # Guards the @all_names memo and its generation (issue #527). The memo is a frozen Set,
+    # replaced whole (record! publishes a copy with the new name), so a
+    # caller iterating the set it got can never see it change underneath:
+    # record! runs on broadcast threads while the dispatcher iterates it.
+    @names_lock = Mutex.new
+    # Bumped by every record! and reset_cache! (under @names_lock): a cold
+    # load publishes its snapshot only if no such change happened while it ran.
+    @names_generation = 0
+
     class << self
       # Inserts the physical queue name. Idempotent and cheap to call on
       # every broadcast; the caller (`ensure_stream_queue`) also memoizes
@@ -61,7 +70,10 @@ module Pgbus
         # already-registered stream until the next reset_cache!. Leaving it
         # nil lets the next all_names call do a real load, which already
         # includes this row since the insert above has committed.
-        @all_names&.add(queue_name)
+        @names_lock.synchronize do
+          @names_generation += 1
+          @all_names = (@all_names | [queue_name]).freeze if @all_names
+        end
         true
       rescue ActiveRecord::ActiveRecordError => e
         Pgbus.logger.debug { "[Pgbus] Failed to record stream queue #{queue_name}: #{e.message}" }
@@ -76,8 +88,21 @@ module Pgbus
       # not one per queue. Callers that need freshness (a long-lived process
       # picking up newly-created streams) call `reset_cache!` at the top of
       # their loop.
+      # A cold load runs outside the lock (record! takes a connection before
+      # the lock, so a load holding the lock while it waits for a connection
+      # could deadlock an exhausted pool) and is published only when no
+      # record! or reset_cache! ran meanwhile: its snapshot could predate
+      # them, and publishing it would lose their change. Otherwise the caller
+      # gets the snapshot and the memo stays empty, so the next call reloads.
       def all_names
-        @all_names ||= load_names
+        cached, generation = @names_lock.synchronize { [@all_names, @names_generation] }
+        return cached if cached
+
+        loaded = load_names.freeze
+        @names_lock.synchronize do
+          @all_names ||= loaded if @names_generation == generation
+          @all_names || loaded
+        end
       end
 
       # Registry ∪ fingerprint-matched names. Use this for classification
@@ -128,11 +153,17 @@ module Pgbus
       # wildcard resolution so freshly-created streams are picked up without
       # a process restart.
       def reset_cache!
-        @all_names = nil
+        @names_lock.synchronize do
+          @names_generation += 1
+          @all_names = nil
+        end
       end
 
       # Memoized like StreamStat: a successful probe sticks; a transient
       # error returns false without caching, so the next call retries.
+      # An idempotent memo: concurrent first callers probe the same schema
+      # and store the same Boolean, so the unlocked read/write is safe.
+      # rubocop:disable-next ThreadSafety/ClassInstanceVariable
       def table_exists?
         return @table_exists if defined?(@table_exists) && @table_exists
 

data/app/models/pgbus/stream_stat.rb

@@ -49,6 +49,9 @@ module Pgbus
     # false on the first hiccup would permanently disable stream
     # stats for the process lifetime, which is a worse failure mode
     # than a few retries.
+    # An idempotent schema memo: concurrent first callers probe the same
+    # schema and store the same Boolean, so the unlocked read/write is safe.
+    # rubocop:disable-next ThreadSafety/ClassInstanceVariable
     def self.table_exists?
       return @table_exists if defined?(@table_exists)
 

data/app/views/layouts/pgbus/application.html.erb

@@ -126,6 +126,7 @@
               <%= pgbus_nav_link t("pgbus.layout.nav.queues"), pgbus.queues_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.jobs"), pgbus.jobs_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.recurring"), pgbus.recurring_tasks_path %>
+              <%= pgbus_nav_link t("pgbus.layout.nav.deploy_tasks"), pgbus.deploy_tasks_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.processes"), pgbus.processes_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.events"), pgbus.events_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.batches"), pgbus.batches_path %>
@@ -186,6 +187,7 @@
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.queues"), pgbus.queues_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.jobs"), pgbus.jobs_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.recurring"), pgbus.recurring_tasks_path %>
+          <%= pgbus_mobile_nav_link t("pgbus.layout.nav.deploy_tasks"), pgbus.deploy_tasks_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.processes"), pgbus.processes_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.events"), pgbus.events_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.batches"), pgbus.batches_path %>

data/app/views/pgbus/deploy_tasks/_rollover_banner.html.erb

@@ -0,0 +1,25 @@
+<%# The rollover the scheduler acts on (DataSource#deploy_rollover): the same
+    reason every waiting task's sentence names. %>
+<% key = pgbus_deploy_rollover_key(@rollover) %>
+<% lagging = Array(@rollover&.dig(:lagging)) %>
+<section aria-labelledby="deploy-rollover-heading" data-rollover="<%= key %>"
+         class="mb-6 rounded-lg p-4 ring-1 <%= Pgbus::DeployTasksHelper::BANNER_TONE_CSS.fetch(pgbus_deploy_rollover_tone(@rollover)) %>">
+  <h2 id="deploy-rollover-heading" class="text-sm font-semibold"><%= t("pgbus.deploy_tasks.banner.heading") %></h2>
+  <p class="mt-1 text-sm"><%= pgbus_deploy_rollover_sentence(@rollover) %></p>
+  <% if key == "no_revision" %>
+    <p class="mt-1 text-sm"><%= t("pgbus.deploy_tasks.banner.no_revision_hint_html") %></p>
+  <% end %>
+  <% if lagging.any? %>
+    <ul class="mt-2 list-disc pl-5 text-sm">
+      <% lagging.first(10).each do |process| %>
+        <li><%= pgbus_deploy_lagging_process(process) %></li>
+      <% end %>
+      <% if lagging.size > 10 %>
+        <li><%= t("pgbus.deploy_tasks.banner.lagging_more", count: lagging.size - 10) %></li>
+      <% end %>
+    </ul>
+  <% end %>
+  <% if @rollover&.dig(:live_by_revision).present? %>
+    <p class="mt-2 text-xs"><%= t("pgbus.deploy_tasks.banner.live_heading") %> <%= pgbus_deploy_live_counts(@rollover) %></p>
+  <% end %>
+</section>