pgbus 0.19.0 → 0.19.1

data/README.md

@@ -1217,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
@@ -2216,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:
@@ -2290,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) |
 
@@ -2388,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/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" %>

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

@@ -0,0 +1,134 @@
+<% result = Pgbus::Web::DeployTaskState.present(@task, @rollover) %>
+<% last_run = pgbus_deploy_last_run(@task) %>
+<div class="mb-6">
+  <div class="flex items-center justify-between">
+    <div>
+      <h1 class="text-2xl font-bold text-gray-900 dark:text-white"><%= @task[:key] %></h1>
+      <p class="mt-1 text-sm text-gray-500 dark:text-gray-400"><%= @task[:class_name] || @task[:command] %></p>
+    </div>
+    <div class="flex space-x-2">
+      <%= 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 %>
+      <% if @task[:enabled] %>
+        <%= pgbus_button_to t("pgbus.deploy_tasks.run_now"), pgbus.enqueue_deploy_task_path(@task[:id]), variant: :primary %>
+      <% end %>
+      <%= pgbus_link_to t("pgbus.deploy_tasks.show.back"), pgbus.deploy_tasks_path, variant: :secondary %>
+    </div>
+  </div>
+</div>
+
+<div class="grid grid-cols-1 lg:grid-cols-3 gap-6 mb-8">
+  <div class="rounded-lg bg-white dark:bg-gray-800 p-5 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+    <p class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.state") %></p>
+    <p class="mt-1"><%= pgbus_deploy_state_badge(result) %></p>
+    <p class="mt-1 text-xs text-gray-600 dark:text-gray-300"><%= pgbus_deploy_task_reason(result) %></p>
+  </div>
+
+  <div class="rounded-lg bg-white dark:bg-gray-800 p-5 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+    <p class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.version") %></p>
+    <p class="mt-1 text-lg font-semibold text-gray-900 dark:text-white"><%= pgbus_deploy_version(@task) %></p>
+  </div>
+
+  <div class="rounded-lg bg-white dark:bg-gray-800 p-5 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+    <p class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.last_run") %></p>
+    <% if last_run %>
+      <p class="mt-1 text-lg font-semibold text-gray-900 dark:text-white"><%= pgbus_time(last_run[:run_at]) %></p>
+      <p class="text-xs text-gray-500 dark:text-gray-400"><%= pgbus_absolute_time(last_run[:run_at]) %> · <%= t("pgbus.deploy_tasks.triggered_by.#{last_run[:triggered_by]}") %></p>
+    <% else %>
+      <p class="mt-1 text-lg font-semibold text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.tasks_table.never") %></p>
+    <% end %>
+  </div>
+</div>
+
+<div class="rounded-lg bg-white dark:bg-gray-800 shadow ring-1 ring-gray-200 dark:ring-gray-700 mb-8">
+  <div class="px-4 py-3 border-b border-gray-200 dark:border-gray-700">
+    <h2 class="text-lg font-medium text-gray-900 dark:text-white"><%= t("pgbus.deploy_tasks.show.configuration") %></h2>
+  </div>
+  <div class="p-4">
+    <dl class="grid grid-cols-1 sm:grid-cols-2 gap-4">
+      <div>
+        <dt class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.labels.job_class") %></dt>
+        <dd class="mt-1 text-sm text-gray-900 dark:text-white"><%= @task[:class_name] || "—" %></dd>
+      </div>
+      <% if @task[:command] %>
+        <div>
+          <dt class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.labels.command") %></dt>
+          <dd class="mt-1 text-sm text-gray-900 dark:text-white font-mono text-xs"><%= @task[:command] %></dd>
+        </div>
+      <% end %>
+      <div>
+        <dt class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.labels.queue") %></dt>
+        <dd class="mt-1 text-sm text-gray-900 dark:text-white"><%= @task[:queue_name] || t("pgbus.deploy_tasks.default_queue") %></dd>
+      </div>
+      <div>
+        <dt class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.labels.priority") %></dt>
+        <dd class="mt-1 text-sm text-gray-900 dark:text-white"><%= @task[:priority] %></dd>
+      </div>
+      <% if @task[:armed_for] && @task[:armed_at] %>
+        <div>
+          <dt class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.labels.armed") %></dt>
+          <dd class="mt-1 text-sm text-gray-900 dark:text-white"><%= t("pgbus.deploy_tasks.show.armed_html", ago: pgbus_time(@task[:armed_at]),
+                armed_for: @task[:every_deploy] ? @task[:armed_for] : t("pgbus.deploy_tasks.version", version: @task[:armed_for])) %></dd>
+        </div>
+      <% end %>
+      <% if @task[:arguments]&.any? %>
+        <div class="sm:col-span-2">
+          <dt class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.labels.arguments") %></dt>
+          <dd class="mt-1 text-sm text-gray-900 dark:text-white font-mono text-xs"><%= @task[:arguments].inspect %></dd>
+        </div>
+      <% end %>
+      <% if @task[:description] %>
+        <div class="sm:col-span-2">
+          <dt class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.labels.description") %></dt>
+          <dd class="mt-1 text-sm text-gray-900 dark:text-white"><%= @task[:description] %></dd>
+        </div>
+      <% end %>
+      <div>
+        <dt class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.deploy_tasks.show.labels.source") %></dt>
+        <dd class="mt-1 text-sm text-gray-900 dark:text-white"><%= @task[:static] ? t("pgbus.deploy_tasks.show.source_config") : t("pgbus.deploy_tasks.show.source_dynamic") %></dd>
+      </div>
+    </dl>
+  </div>
+</div>
+
+<div class="rounded-lg bg-white dark:bg-gray-800 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+  <div class="px-4 py-3 border-b border-gray-200 dark:border-gray-700">
+    <h2 class="text-lg font-medium text-gray-900 dark:text-white"><%= t("pgbus.deploy_tasks.show.recent_runs") %></h2>
+  </div>
+  <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.show.run_headers.triggered_by") %></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.show.run_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.show.run_headers.revision") %></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.show.run_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.show.run_headers.enqueued_at") %></th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+      <% Array(@task[:runs]).each do |run| %>
+        <tr class="hover:bg-gray-50 dark:hover:bg-gray-700/50">
+          <td data-label="<%= t("pgbus.deploy_tasks.show.run_headers.triggered_by") %>" class="px-4 py-3 text-sm text-gray-900 dark:text-white">
+            <%= t("pgbus.deploy_tasks.triggered_by.#{run[:triggered_by]}") %>
+          </td>
+          <td data-label="<%= t("pgbus.deploy_tasks.show.run_headers.version") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300">
+            <%= t("pgbus.deploy_tasks.version", version: run[:version]) %>
+          </td>
+          <td data-label="<%= t("pgbus.deploy_tasks.show.run_headers.revision") %>" class="px-4 py-3 text-sm font-mono text-gray-600 dark:text-gray-300">
+            <%= run[:revision] || "—" %>
+          </td>
+          <td data-label="<%= t("pgbus.deploy_tasks.show.run_headers.queue") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300">
+            <%= run[:queue_name] || "—" %>
+          </td>
+          <td data-label="<%= t("pgbus.deploy_tasks.show.run_headers.enqueued_at") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300">
+            <%= pgbus_time(run[:run_at]) %>
+          </td>
+        </tr>
+      <% end %>
+      <% if Array(@task[:runs]).empty? %>
+        <%= render "pgbus/shared/empty_row", colspan: 5, message: t("pgbus.deploy_tasks.show.no_runs") %>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/config/i18n-tasks.yml

@@ -39,6 +39,8 @@ ignore_unused:
   - "pgbus.dashboard.queue_health.words.*"
   - "pgbus.insights.show.charts.series_name"
   - "pgbus.recurring_tasks.index.task_count.*"
+  - "pgbus.deploy_tasks.banner.lagging_html.*"
+  - "pgbus.deploy_tasks.reasons.waiting_lagging_html.*"
   - "pgbus.processes.state.activity.schedule.*"
   - "pgbus.processes.state.activity.slots.*"
   - "pgbus.processes.state.activity.threads.*"