pgbus 0.19.0 → 0.19.2

data/README.md

@@ -801,28 +801,27 @@ How Pgbus integrates with your application's transactions and tracks groups of r
 Coordinate groups of jobs with callbacks when all complete:
 
 ```ruby
-batch = Pgbus::Batch.new(
-  on_finish: BatchFinishedJob,
-  on_success: BatchSucceededJob,
-  on_discard: BatchFailedJob,
-  description: "Import users",
-  properties: { initiated_by: current_user.id }
-)
-
-batch.enqueue do
-  users.each { |user| ImportUserJob.perform_later(user.id) }
+batch = Pgbus.batch(description: "Import users", properties: { initiated_by: current_user.id }) do |b|
+  b.on_complete BatchFinishedJob
+  b.on_success  BatchSucceededJob
+  b.on_failure  BatchFailedJob
+  b.add(*users.map { |user| ImportUserJob.new(user.id) })
 end
 ```
 
+`b.add` takes job instances (each keeps its own `.set(wait:, queue:)`) and sends them in one bulk enqueue. The batch row exists before the block runs and stays pending until it returns, so a job that finishes while the block is still adding cannot finish the batch early. Set callbacks first: if the block raises after an `add`, the added jobs still run and the batch finishes later with only the callbacks set by then. A block that goes `config.batch_stall_threshold` (default 5 minutes) without adding a job is started by the stalled-batch sweep, so keep slow work outside it. Callbacks are job classes or configured instances, never blocks: they are stored on the batch row.
+
+Inside a job, `batch { |b| ... }` opens a new batch the same way, and a job that is already a member adds siblings with `batch.add(NextJob.new(id))`. `Pgbus::Batch.new(on_complete: ...)` plus `batch.enqueue { ... }` remains the lower-level form.
+
 #### Callbacks
 
 | Callback | Fired when |
 |----------|------------|
-| `on_finish` | All jobs completed (success or discard) |
-| `on_success` | All jobs completed successfully (zero discarded) |
-| `on_discard` | At least one job was dead-lettered |
+| `on_complete` | All jobs completed (success or failure). `on_finish` is a deprecated alias until 1.0 |
+| `on_success` | All jobs completed successfully (zero failed) |
+| `on_failure` | At least one job was dead-lettered. `on_discard` is a deprecated alias until 1.0 |
 
-Callback jobs receive the batch `properties` hash as their argument:
+Callback jobs given as a bare class receive the batch `properties` hash as their argument:
 
 ```ruby
 class BatchFinishedJob < ApplicationJob
@@ -838,23 +837,18 @@ end
 `ensures_uniqueness` protects one job. A multi-job run — a nightly import that fans out into hundreds of chunk jobs, a pipeline whose jobs enqueue the next stage — has no single job that lives for the whole run, so a lock on the entry job releases the moment that job finishes and the next scheduler tick starts a second run on top of the first. Give the batch the lock instead:
 
 ```ruby
-batch = Pgbus::Batch.new(
-  uniqueness_key: "perfecta-daily",
-  on_conflict: :discard,           # :reject (raise AlreadyRunning), :discard, :log
-  on_success: ExportPricesJob
-)
-
-batch.enqueue do
-  ImportChunkJob.perform_later("products", 0)
+Pgbus.batch(uniqueness_key: "perfecta-daily", on_conflict: :discard) do |b|   # :reject (raise AlreadyRunning), :discard, :log
+  b.on_success ExportPricesJob
+  b.add(ImportChunkJob.new("products", 0))
 end
 ```
 
-The lock is taken at `enqueue` and held until the batch finishes — through every open-batch `batch.enqueue` add from inside a running job — then released in the same single-winner finish that fires the callbacks, so completion, the stalled-batch sweep and cleanup all release it. While it is held, another `Pgbus::Batch.new(uniqueness_key: "perfecta-daily").enqueue { ... }` raises `Pgbus::Batch::AlreadyRunning` (`:reject`), or skips its block and returns a batch that answers `discarded?` (`:discard`, `:log`). The row lives in `pgbus_uniqueness_keys` as `batch:<key>`, so it never collides with a job's key and shows up in the dashboard like any other lock; the reaper judges it by the batch's status, never by queue contents.
+The lock is taken at the top of the block (or at `enqueue`) and held until the batch finishes — through every open-batch `batch.add` from inside a running job — then released in the same single-winner finish that fires the callbacks, so completion, the stalled-batch sweep and cleanup all release it. While it is held, another `Pgbus.batch(uniqueness_key: "perfecta-daily") { ... }` raises `Pgbus::Batch::AlreadyRunning` (`:reject`), or skips its block and returns a batch that answers `discarded?` (`:discard`, `:log`). The row lives in `pgbus_uniqueness_keys` as `batch:<key>`, so it never collides with a job's key and shows up in the dashboard like any other lock; the reaper judges it by the batch's status, never by queue contents.
 
 #### How batches work
 
-1. `Batch.new(...)` creates a tracking row in `pgbus_batches` with `status: "pending"`
-2. `batch.enqueue { ... }` tags each enqueued job with the `pgbus_batch_id` in its payload
+1. The top of the `Pgbus.batch` block (or the first `batch.enqueue`) creates a tracking row in `pgbus_batches` with `status: "pending"`
+2. Each job enqueued in the block is tagged with the `pgbus_batch_id` in its payload
 3. After each job completes or is dead-lettered, the executor atomically updates the batch counters
 4. When `completed_jobs + discarded_jobs == total_jobs`, the batch status flips to `"finished"` and callback jobs are enqueued
 5. The dispatcher cleans up finished batches older than 7 days
@@ -1017,7 +1011,7 @@ c.metrics_backend = MyOpenTelemetryBackend.new
 | `pgbus_queue_job_count` | counter | `queue`, `job_class`, `status` (`processed`/`failed`/`dead_lettered`) |
 | `pgbus_visibility_extended` | counter | `queue`, `job_class` — one per re-armed visibility timeout; a class listed here outlives `visibility_timeout` |
 | `pgbus_job_duration_ms` | histogram | `queue`, `job_class` |
-| `pgbus_event_count` | counter | `handler`, `routing_key`, `status` |
+| `pgbus_event_count` | counter | `handler`, `routing_key`, `status` (`processed`/`failed`/`skipped`/`dead_lettered`), plus `reason` on `skipped` only (`completed`/`cached`/`owned`) |
 | `pgbus_event_duration_ms` | histogram | `handler`, `routing_key` |
 | `pgbus_messages_sent` / `pgbus_messages_read` | counter | `queue` |
 | `pgbus_stream_broadcast_count` | counter | `stream`, `deferred` |
@@ -1052,7 +1046,7 @@ ActiveSupport::Notifications.subscribe(/^pgbus\./) do |name, start, finish, _id,
 end
 ```
 
-Metrics-relevant events emitted (the subset the metrics subscriber maps; see `lib/pgbus/instrumentation.rb` for the full `pgbus.*` catalog): `pgbus.executor.execute`, `pgbus.job_completed`, `pgbus.job_failed`, `pgbus.job_dead_lettered`, `pgbus.event_processed`, `pgbus.event_failed`, `pgbus.client.send_message`, `pgbus.client.send_batch`, `pgbus.client.read_batch`, `pgbus.client.pool`, `pgbus.stream.broadcast`, `pgbus.outbox.publish`, `pgbus.recurring.enqueue`, `pgbus.worker.recycle`, `pgbus.consumer.recycle`. Payload keys are documented in `lib/pgbus/instrumentation.rb`.
+Metrics-relevant events emitted (the subset the metrics subscriber maps; see `lib/pgbus/instrumentation.rb` for the full `pgbus.*` catalog): `pgbus.executor.execute`, `pgbus.job_completed`, `pgbus.job_failed`, `pgbus.job_dead_lettered`, `pgbus.event_processed`, `pgbus.event_failed`, `pgbus.event_dead_lettered`, `pgbus.event_skipped`, `pgbus.job_visibility_extended`, `pgbus.client.send_message`, `pgbus.client.send_batch`, `pgbus.client.read_batch`, `pgbus.client.pool`, `pgbus.stream.broadcast`, `pgbus.outbox.publish`, `pgbus.recurring.enqueue`, `pgbus.worker.recycle`, `pgbus.consumer.recycle`. Payload keys are documented in `lib/pgbus/instrumentation.rb`.
 
 ### Connection pool metrics
 
@@ -1217,6 +1211,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
@@ -2216,6 +2211,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:
@@ -2290,6 +2321,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) |
 
@@ -2388,6 +2421,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/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/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>

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

@@ -0,0 +1,71 @@
+<turbo-frame id="deploy-tasks" data-auto-refresh data-turbo-action="advance"
+             data-src="<%= pgbus.deploy_tasks_path(request.query_parameters.merge(frame: "deploy_tasks")) %>">
+  <%= render "pgbus/deploy_tasks/rollover_banner" %>
+  <div class="rounded-lg bg-white dark:bg-gray-800 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+    <table class="pgbus-table min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+      <thead class="bg-gray-50 dark:bg-gray-900">
+        <tr>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.tasks_table.headers.task") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.tasks_table.headers.version") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.tasks_table.headers.queue") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.tasks_table.headers.last_run") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.tasks_table.headers.state") %></th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.tasks_table.headers.actions") %></th>
+        </tr>
+      </thead>
+      <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+        <% @deploy_tasks.each do |task| %>
+          <% result = Pgbus::Web::DeployTaskState.present(task, @rollover) %>
+          <% last_run = pgbus_deploy_last_run(task) %>
+          <tr data-state="<%= result.state %>" class="hover:bg-gray-50 dark:hover:bg-gray-700/50">
+            <td data-label="<%= t("pgbus.deploy_tasks.tasks_table.headers.task") %>" class="px-4 py-3">
+              <div>
+                <%= pgbus_link_to task[:key], pgbus.deploy_task_path(task[:id]), data: { turbo_frame: "_top" } %>
+              </div>
+              <div class="text-xs text-gray-500 dark:text-gray-400"><%= task[:class_name] || task[:command]&.truncate(40) %></div>
+              <% if task[:description] %>
+                <div class="text-xs text-gray-500 dark:text-gray-400 mt-0.5"><%= task[:description] %></div>
+              <% end %>
+            </td>
+            <td data-label="<%= t("pgbus.deploy_tasks.tasks_table.headers.version") %>" class="px-4 py-3 text-sm text-gray-900 dark:text-white">
+              <%= pgbus_deploy_version(task) %>
+            </td>
+            <td data-label="<%= t("pgbus.deploy_tasks.tasks_table.headers.queue") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300">
+              <%= task[:queue_name] || t("pgbus.deploy_tasks.default_queue") %>
+            </td>
+            <td data-label="<%= t("pgbus.deploy_tasks.tasks_table.headers.last_run") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300">
+              <% if last_run %>
+                <%= pgbus_time(last_run[:run_at]) %>
+                <span class="block text-xs text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.triggered_by.#{last_run[:triggered_by]}") %></span>
+              <% else %>
+                <%= t("pgbus.deploy_tasks.tasks_table.never") %>
+              <% end %>
+            </td>
+            <td data-label="<%= t("pgbus.deploy_tasks.tasks_table.headers.state") %>" class="px-4 py-3">
+              <%= pgbus_deploy_state_badge(result) %>
+              <p class="mt-1 text-xs text-gray-600 dark:text-gray-300"><%= pgbus_deploy_task_reason(result) %></p>
+            </td>
+            <td data-label="<%= t("pgbus.deploy_tasks.tasks_table.headers.actions") %>" class="px-4 py-3 text-right space-x-1">
+              <%= pgbus_button_to task[:enabled] ? t("pgbus.deploy_tasks.disable") : t("pgbus.deploy_tasks.enable"),
+                  pgbus.toggle_deploy_task_path(task[:id]),
+                  variant: task[:enabled] ? :warning : :success, size: :sm, form: { data: { turbo_frame: "_top" } } %>
+              <% if task[:enabled] %>
+                <%= pgbus_button_to t("pgbus.deploy_tasks.run_now"), pgbus.enqueue_deploy_task_path(task[:id]),
+                    variant: :primary, size: :sm, form: { data: { turbo_frame: "_top" } } %>
+              <% end %>
+            </td>
+          </tr>
+        <% end %>
+        <% if @deploy_tasks.empty? %>
+          <%= render "pgbus/shared/empty_row", colspan: 6,
+                message: safe_join([content_tag(:p, t("pgbus.deploy_tasks.tasks_table.empty_title"), class: "text-lg font-medium"),
+                                    content_tag(:p, t("pgbus.deploy_tasks.tasks_table.empty_hint_html"), class: "mt-1")]) %>
+        <% end %>
+      </tbody>
+    </table>
+    <%= render "pgbus/shared/pager", page: @page, per_page: @per_page, shown: @deploy_tasks.size,
+          total_count: @deploy_tasks_count.total,
+          has_more: @deploy_tasks_count.capped? && @deploy_tasks.size == @per_page,
+          page_path: ->(n) { pgbus.deploy_tasks_path(page: n) } %>
+  </div>
+</turbo-frame>

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

@@ -0,0 +1,6 @@
+<div class="flex items-center justify-between mb-6">
+  <h1 class="text-2xl font-bold text-gray-900 dark:text-white"><%= t("pgbus.deploy_tasks.index.title") %></h1>
+  <span class="text-sm text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.index.task_count", count: @deploy_tasks_count.total) %></span>
+</div>
+
+<%= render "pgbus/deploy_tasks/tasks_table" %>