pgbus 0.19.4 → 0.20.1

data/app/models/pgbus/workflow_step.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Pgbus
+  # One step attempt (pgbus_workflow_steps). The unique (workflow_id,
+  # step_name, attempt) index makes a duplicate attempt impossible, and the
+  # guarded claim (scheduled → in_progress) makes a duplicate StepJob a no-op.
+  #
+  # The after-commit callback below is the ONLY place a
+  # Pgbus::Workflow::StepJob is enqueued: start!, an advance, a reattempt,
+  # resume!, run_now!, and the sweep all write a row (a new scheduled row, or
+  # a bumped enqueued_at) and let it fire once the write is visible, even
+  # inside an application transaction.
+  class WorkflowStep < BusRecord
+    self.table_name = "pgbus_workflow_steps"
+
+    after_save_commit :enqueue_step_job, if: :needs_enqueue?
+
+    # Inserts the next attempt of +step_name+: one more than the highest
+    # attempt so far (1 for a step that never ran).
+    def self.insert_next!(workflow_id:, workflow_class:, step_name:, scheduled_at:)
+      attempt = where(workflow_id: workflow_id, step_name: step_name).maximum(:attempt).to_i + 1
+      create!(workflow_id: workflow_id, workflow_class: workflow_class, step_name: step_name, attempt: attempt,
+              status: "scheduled", scheduled_at: scheduled_at, created_at: Time.current)
+    end
+
+    # scheduled → in_progress, only once the row is due (a second of slack
+    # for clock skew between the sender and this worker). A message that
+    # arrives early (left behind by reschedule! to a later time) claims
+    # nothing; the later send does. Returns the number of rows claimed.
+    def self.claim!(id, now:, stall_at:, msg_id:, worker:, app_revision:)
+      where(id: id, status: "scheduled").where(scheduled_at: ..(now + 1))
+                                        .update_all(status: "in_progress", started_at: now, stall_at: stall_at,
+                                                    msg_id: msg_id, worker: worker, app_revision: app_revision)
+    end
+
+    # Records an attempt's outcome, only while the row is still in_progress.
+    # 0 means the attempt was declared stalled (or the run cancelled) while
+    # it was still running: its outcome is not applied.
+    def self.finish!(id, **attrs)
+      where(id: id, status: "in_progress").update_all(attrs)
+    end
+
+    # in_progress → waiting: the step parks on a signal or its fan-out batch
+    # (Workflow::Waiting). Returns the number of rows moved.
+    def self.park!(id, **attrs)
+      where(id: id, status: "in_progress").update_all(attrs.merge(status: "waiting"))
+    end
+
+    # waiting → in_progress, so the outcome of a finished wait (the batch
+    # finished, the wait timed out, an operator skipped it) is applied like
+    # any attempt's. Returns the number of rows moved.
+    def self.unpark!(id)
+      where(id: id, status: "waiting").update_all(status: "in_progress")
+    end
+
+    # A waiting row's next deadline (on_timeout: :notify keeps the attempt
+    # waiting). Written without the model callback, so no StepJob goes out.
+    # Returns the number of rows moved.
+    def self.move_deadline!(id, timeout_at:)
+      where(id: id, status: "waiting").update_all(timeout_at: timeout_at)
+    end
+
+    # waiting rows of waiting runs past their timeout_at (the sweep applies
+    # their on_timeout).
+    def self.wait_expired(now: Time.current)
+      where(status: "waiting").where(timeout_at: ...now)
+                              .where(workflow_id: WorkflowEntry.where(status: "waiting").select(:workflow_id))
+    end
+
+    # The scheduled, waiting and in_progress rows of a run, cancelled (an
+    # outside cancel!, a resume_at!).
+    def self.cancel_open!(workflow_id, now: Time.current)
+      where(workflow_id: workflow_id, status: Workflow::States::OPEN_STEP)
+        .update_all(status: "cancelled", outcome: "cancelled", finished_at: now)
+    end
+
+    # The newest row of a run: the step it is on.
+    def self.latest_for(workflow_id)
+      where(workflow_id: workflow_id).order(id: :desc).first
+    end
+
+    # How many of +step_name+'s latest finished attempts in a row were
+    # reattempted (what max_reattempts counts). Any other outcome, such as a
+    # pause an operator resumed, ends the run of reattempts.
+    def self.consecutive_reattempts(workflow_id, step_name)
+      outcomes = where(workflow_id: workflow_id, step_name: step_name).where.not(outcome: nil)
+                                                                      .order(attempt: :desc).pluck(:outcome)
+      outcomes.take_while { |outcome| outcome == "reattempted" }.size
+    end
+
+    def self.completed_output(workflow_id, step_name)
+      where(workflow_id: workflow_id, step_name: step_name.to_s, status: "completed").order(attempt: :desc).pick(:output)
+    end
+
+    # { step_name => output } of each step's latest completed attempt.
+    def self.completed_outputs(workflow_id)
+      where(workflow_id: workflow_id, status: "completed").order(:attempt).pluck(:step_name, :output).to_h
+    end
+
+    # in_progress rows past their stall_at.
+    def self.stalled(now: Time.current)
+      where(status: "in_progress").where(stall_at: ...now)
+    end
+
+    # scheduled rows of ready runs, due more than +threshold+ ago and not
+    # sent within it: the sweep sends them again.
+    def self.overdue(threshold:, now: Time.current)
+      cutoff = now - threshold
+      where(status: "scheduled").where(scheduled_at: ...cutoff)
+                                .where("enqueued_at IS NULL OR enqueued_at < ?", cutoff)
+                                .where(workflow_id: WorkflowEntry.where(status: "ready").select(:workflow_id))
+    end
+
+    # Fires on a new scheduled row, on a change to scheduled, and on a
+    # bumped enqueued_at; never on any other save.
+    def needs_enqueue?
+      status == "scheduled" && (previously_new_record? || saved_change_to_status? || saved_change_to_enqueued_at?)
+    end
+
+    private
+
+    # Runs after commit, so a failure cannot roll back the row: it is
+    # reported, and the sweep sends the step again once it is
+    # workflow_stall_threshold overdue.
+    def enqueue_step_job
+      job = Workflow::StepJob.set(**step_job_set_options).perform_later(id)
+      update_columns(enqueued_at: Time.current, job_id: job.job_id) if job
+    rescue StandardError => e
+      Pgbus.logger.error do
+        "[Pgbus] Workflow StepJob for step #{id} (#{step_name}) could not be enqueued: #{e.class}: #{e.message}"
+      end
+      ErrorReporter.report(e, { action: "workflow_step_enqueue", workflow_class: workflow_class,
+                                workflow_id: workflow_id, step_name: step_name, attempt: attempt })
+    end
+
+    # queue/priority from the class and the step (step wins), sent at
+    # scheduled_at (which already holds any job_options wait/wait_until, see
+    # Workflow::Runner.schedule!).
+    def step_job_set_options
+      klass = workflow_class.safe_constantize
+      options = klass.is_a?(Class) && klass < Workflow ? klass.step_job_options_for(step_name) : {}
+      set = { queue: options[:queue] || Pgbus.configuration.workflow_queue, priority: options[:priority] }
+      set[:wait_until] = scheduled_at if scheduled_at > Time.current
+      set.compact
+    end
+  end
+end

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

@@ -130,6 +130,7 @@
               <%= 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 %>
+              <%= pgbus_nav_link t("pgbus.layout.nav.workflows"), pgbus.workflows_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.dlq"), pgbus.dead_letter_index_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.outbox"), pgbus.outbox_index_path %>
               <%= pgbus_nav_link t("pgbus.layout.nav.locks"), pgbus.locks_path %>
@@ -191,6 +192,7 @@
           <%= 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 %>
+          <%= pgbus_mobile_nav_link t("pgbus.layout.nav.workflows"), pgbus.workflows_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.dlq"), pgbus.dead_letter_index_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.outbox"), pgbus.outbox_index_path %>
           <%= pgbus_mobile_nav_link t("pgbus.layout.nav.locks"), pgbus.locks_path %>

data/app/views/pgbus/dashboard/_stats_cards.html.erb

@@ -77,6 +77,23 @@
       <p class="text-xs text-gray-600 dark:text-gray-300"><%= throughput[:available] ? t("pgbus.dashboard.stats_cards.throughput_detail", minutes: throughput[:window_minutes]) : t("pgbus.dashboard.stats_cards.throughput_unavailable") %></p>
     <% end %>
 
+    <%# Two links in one card (the list and the attention view), so the card
+        is a div; its title and number link to the list. %>
+    <% workflows = @workflow_counts %>
+    <div data-testid="workflows-card" class="<%= card %>">
+      <%= link_to pgbus.workflows_path, data: { turbo_frame: "_top" }, class: "block" do %>
+        <p class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.dashboard.stats_cards.workflows") %></p>
+        <p class="<%= number %>"><%= number_with_delimiter(workflows[:ongoing]) %></p>
+      <% end %>
+      <p class="text-xs text-gray-600 dark:text-gray-300">
+        <%= t("pgbus.dashboard.stats_cards.workflows_detail", paused: workflows[:paused]) %>
+        <% if workflows[:attention].positive? %>
+          · <%= pgbus_link_to t("pgbus.dashboard.stats_cards.workflows_attention", count: workflows[:attention]),
+                  pgbus.attention_workflows_path, size: :sm, tone: :yellow, data: { turbo_frame: "_top" } %>
+        <% end %>
+      </p>
+    </div>
+
     <%= link_to pgbus.locks_path, data: { turbo_frame: "_top" }, class: card do %>
       <p class="text-sm font-medium text-gray-500 dark:text-gray-400"><%= t("pgbus.dashboard.stats_cards.parked_jobs") %></p>
       <p class="mt-1 text-3xl font-semibold <%= @stats[:parked_total].to_i > 0 ? 'text-amber-600 dark:text-amber-400' : 'text-gray-900 dark:text-white' %>">

data/app/views/pgbus/workflows/_actions.html.erb

@@ -0,0 +1,59 @@
+<%# The operator actions (issue #542). Which buttons show is
+    available_actions (Workflow::States), never view logic; every button
+    submits the one form, to its own formaction, so the reason typed once
+    goes with whichever is pressed. %>
+<% actions = pgbus_workflow_dashboard_actions(@workflow) %>
+<% if actions.any? %>
+  <% id = @workflow[:workflow_id] %>
+  <%# The form's own action is the first button's, so Enter in the reason box
+      does what the first button does (and asks to confirm it). %>
+  <% paths = { resume: pgbus.resume_workflow_path(id), run_now: pgbus.run_now_workflow_path(id),
+               skip: pgbus.skip_step_workflow_path(id), rerun: pgbus.rerun_workflow_path(id),
+               cancel: pgbus.cancel_workflow_path(id), resume_at: pgbus.resume_at_workflow_path(id) } %>
+  <% default_path = paths.fetch(paths.keys.find { |action| actions.include?(action) }) %>
+  <section class="mb-8 rounded-lg bg-white dark:bg-gray-800 p-4 shadow ring-1 ring-gray-200 dark:ring-gray-700" aria-labelledby="workflow-actions-title" data-testid="workflow-actions">
+    <h2 id="workflow-actions-title" class="text-lg font-medium text-gray-900 dark:text-white"><%= t("pgbus.workflows.show.actions") %></h2>
+    <form action="<%= default_path %>" method="post" data-turbo-frame="_top" class="mt-3">
+      <%= hidden_field_tag :authenticity_token, form_authenticity_token, id: nil %>
+      <div class="max-w-xl">
+        <label for="workflow-action-reason" class="block text-sm font-medium text-gray-700 dark:text-gray-300"><%= t("pgbus.workflows.show.reason_label") %></label>
+        <input type="text" autocomplete="off" id="workflow-action-reason" name="reason" maxlength="1000" aria-describedby="workflow-action-reason-hint" class="<%= Pgbus::WorkflowsHelper::INPUT_CSS %>">
+        <p id="workflow-action-reason-hint" class="mt-1 text-xs text-gray-600 dark:text-gray-300"><%= t("pgbus.workflows.show.reason_hint") %></p>
+      </div>
+      <div class="mt-4 flex flex-wrap items-end gap-2">
+        <% if actions.include?(:resume) %>
+          <%= pgbus_button_tag pgbus_workflow_resume_label(@workflow), variant: :success, formaction: pgbus.resume_workflow_path(id),
+                confirm: t("pgbus.workflows.confirm.resume") %>
+        <% end %>
+        <% if actions.include?(:run_now) %>
+          <%= pgbus_button_tag t("pgbus.workflows.actions.run_now"), variant: :primary, formaction: pgbus.run_now_workflow_path(id),
+                confirm: t("pgbus.workflows.confirm.run_now") %>
+        <% end %>
+        <% if actions.include?(:skip) %>
+          <%= pgbus_button_tag t("pgbus.workflows.actions.skip_step"), variant: :warning, formaction: pgbus.skip_step_workflow_path(id),
+                confirm: t("pgbus.workflows.confirm.skip_step") %>
+        <% end %>
+        <% if actions.include?(:rerun) %>
+          <%= pgbus_button_tag t("pgbus.workflows.actions.rerun"), variant: :primary, formaction: pgbus.rerun_workflow_path(id),
+                confirm: t("pgbus.workflows.confirm.rerun") %>
+        <% end %>
+        <% if actions.include?(:cancel) %>
+          <%= pgbus_button_tag t("pgbus.workflows.actions.cancel"), variant: :danger, formaction: pgbus.cancel_workflow_path(id),
+                confirm: t("pgbus.workflows.confirm.cancel") %>
+        <% end %>
+      </div>
+      <% if actions.include?(:resume_at) && @workflow[:step_names].any? %>
+        <div class="mt-4 flex flex-wrap items-end gap-2">
+          <div>
+            <label for="workflow-resume-step" class="block text-sm font-medium text-gray-700 dark:text-gray-300"><%= t("pgbus.workflows.show.resume_at_label") %></label>
+            <select id="workflow-resume-step" name="step" class="<%= Pgbus::WorkflowsHelper::INPUT_CSS %>">
+              <%= options_for_select(@workflow[:step_names], @workflow[:current_step]) %>
+            </select>
+          </div>
+          <%= pgbus_button_tag t("pgbus.workflows.actions.resume_at"), variant: :secondary, formaction: pgbus.resume_at_workflow_path(id),
+                confirm: t("pgbus.workflows.confirm.resume_at") %>
+        </div>
+      <% end %>
+    </form>
+  </section>
+<% end %>

data/app/views/pgbus/workflows/_events_table.html.erb

@@ -0,0 +1,24 @@
+<%# The audit trail (issue #542): pgbus_workflow_events, newest first, each
+    as "<what> by <actor>: <reason>". %>
+<section class="rounded-lg bg-white dark:bg-gray-800 shadow ring-1 ring-gray-200 dark:ring-gray-700" aria-labelledby="workflow-events-title" data-testid="workflow-events">
+  <h2 id="workflow-events-title" class="px-4 py-3 border-b border-gray-200 dark:border-gray-700 text-lg font-medium text-gray-900 dark:text-white"><%= t("pgbus.workflows.audit.title") %></h2>
+  <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.workflows.audit.headers.when") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.audit.headers.what") %></th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+      <% @workflow[:events].each do |event| %>
+        <tr data-event="<%= event[:event] %>" class="hover:bg-gray-50 dark:hover:bg-gray-700/50">
+          <td data-label="<%= t("pgbus.workflows.audit.headers.when") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300 whitespace-nowrap"><%= pgbus_time(event[:created_at]) %></td>
+          <td data-label="<%= t("pgbus.workflows.audit.headers.what") %>" class="px-4 py-3 text-sm text-gray-900 dark:text-white"><%= pgbus_workflow_event_sentence(event) %></td>
+        </tr>
+      <% end %>
+      <% if @workflow[:events].empty? %>
+        <%= render "pgbus/shared/empty_row", colspan: 2, message: t("pgbus.workflows.audit.empty") %>
+      <% end %>
+    </tbody>
+  </table>
+</section>

data/app/views/pgbus/workflows/_filters.html.erb

@@ -0,0 +1,29 @@
+<%# The filters beyond status (issue #542). A GET form: the filters combine,
+    the status tab is kept, and the pager carries them on. %>
+<% input_css = Pgbus::WorkflowsHelper::INPUT_CSS %>
+<form action="<%= pgbus.workflows_path %>" method="get" data-turbo-frame="_top" data-testid="workflow-filters"
+      class="mb-4 rounded-lg bg-white dark:bg-gray-800 p-4 shadow ring-1 ring-gray-200 dark:ring-gray-700">
+  <input type="hidden" name="status" value="<%= @query.status %>">
+  <div class="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-4">
+    <% Pgbus::Web::WorkflowQuery::TEXT_FILTERS.each do |filter| %>
+      <div>
+        <label for="workflow-filter-<%= filter %>" class="block text-xs font-medium text-gray-700 dark:text-gray-300"><%= t("pgbus.workflows.filters.#{filter}") %></label>
+        <input type="text" autocomplete="off" id="workflow-filter-<%= filter %>" name="<%= filter %>" value="<%= @query.raw[filter] %>" class="<%= input_css %>">
+      </div>
+    <% end %>
+    <% Pgbus::Web::WorkflowQuery::DATE_FILTERS.each do |filter| %>
+      <div>
+        <label for="workflow-filter-<%= filter %>" class="block text-xs font-medium text-gray-700 dark:text-gray-300"><%= t("pgbus.workflows.filters.#{filter}") %></label>
+        <% value = @query.raw[filter] %>
+        <%# A date-time from a shared URL stays a text field, so it survives the next Apply. %>
+        <input type="<%= value.nil? || value.match?(Pgbus::Web::WorkflowQuery::DATE_ONLY) ? "date" : "text" %>" autocomplete="off" id="workflow-filter-<%= filter %>" name="<%= filter %>" value="<%= @query.raw[filter] %>" class="<%= input_css %>">
+      </div>
+    <% end %>
+  </div>
+  <div class="mt-3 flex items-center gap-2">
+    <%= pgbus_button_tag t("pgbus.workflows.filters.apply"), variant: :primary, size: :sm %>
+    <% if @query.filtered? %>
+      <%= pgbus_link_to t("pgbus.workflows.filters.clear"), pgbus.workflows_path(status: @query.status), variant: :secondary, size: :sm %>
+    <% end %>
+  </div>
+</form>

data/app/views/pgbus/workflows/_signal_form.html.erb

@@ -0,0 +1,31 @@
+<%# Send a signal (issue #542). The payload must be a JSON object; the
+    idempotency key is generated per render, so a double submit sends one
+    signal. The name is a select of what the waiting step takes, or free text. %>
+<% id = @workflow[:workflow_id] %>
+<section class="mb-8 rounded-lg bg-white dark:bg-gray-800 p-4 shadow ring-1 ring-gray-200 dark:ring-gray-700" aria-labelledby="workflow-signal-title" data-testid="workflow-signal">
+  <h2 id="workflow-signal-title" class="text-lg font-medium text-gray-900 dark:text-white"><%= t("pgbus.workflows.signal.title") %></h2>
+  <p class="mt-1 text-sm text-gray-600 dark:text-gray-300"><%= t("pgbus.workflows.signal.hint") %></p>
+  <form action="<%= pgbus.signal_workflow_path(id) %>" method="post" data-turbo-frame="_top" class="mt-3 grid max-w-xl grid-cols-1 gap-3">
+    <%= hidden_field_tag :authenticity_token, form_authenticity_token, id: nil %>
+    <input type="hidden" name="idempotency_key" value="<%= SecureRandom.uuid %>">
+    <div>
+      <label for="workflow-signal-name" class="block text-sm font-medium text-gray-700 dark:text-gray-300"><%= t("pgbus.workflows.signal.name") %></label>
+      <% if @workflow[:signal_names].any? %>
+        <select id="workflow-signal-name" name="name" class="<%= Pgbus::WorkflowsHelper::INPUT_CSS %>">
+          <% @workflow[:signal_names].each do |name| %>
+            <option value="<%= name %>"><%= name %></option>
+          <% end %>
+        </select>
+      <% else %>
+        <input type="text" autocomplete="off" id="workflow-signal-name" name="name" required class="<%= Pgbus::WorkflowsHelper::INPUT_CSS %>">
+      <% end %>
+    </div>
+    <div>
+      <label for="workflow-signal-payload" class="block text-sm font-medium text-gray-700 dark:text-gray-300"><%= t("pgbus.workflows.signal.payload") %></label>
+      <textarea id="workflow-signal-payload" name="payload" rows="4" class="<%= Pgbus::WorkflowsHelper::INPUT_CSS %> font-mono">{}</textarea>
+    </div>
+    <div>
+      <%= pgbus_button_tag t("pgbus.workflows.signal.send"), variant: :primary, confirm: t("pgbus.workflows.confirm.signal") %>
+    </div>
+  </form>
+</section>

data/app/views/pgbus/workflows/_signals_table.html.erb

@@ -0,0 +1,40 @@
+<%# The signals delivered to this run (issue #542), newest first. %>
+<section class="mb-8 rounded-lg bg-white dark:bg-gray-800 shadow ring-1 ring-gray-200 dark:ring-gray-700" aria-labelledby="workflow-signals-title" data-testid="workflow-signals">
+  <h2 id="workflow-signals-title" class="px-4 py-3 border-b border-gray-200 dark:border-gray-700 text-lg font-medium text-gray-900 dark:text-white"><%= t("pgbus.workflows.signals.title") %></h2>
+  <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.workflows.signals.headers.name") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.signals.headers.status") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.signals.headers.received") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.signals.headers.claimed") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.signals.headers.consumed") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.signals.headers.idempotency_key") %></th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+      <% @workflow[:signals].each do |signal| %>
+        <tr class="align-top hover:bg-gray-50 dark:hover:bg-gray-700/50">
+          <td data-label="<%= t("pgbus.workflows.signals.headers.name") %>" class="px-4 py-3 text-sm text-gray-900 dark:text-white">
+            <code class="font-mono"><%= signal[:name] %></code>
+            <% payload = Pgbus::Web::PayloadFilter.filter(signal[:payload] || {}) %>
+            <% if payload.any? %>
+              <details class="mt-1">
+                <summary class="inline-flex min-h-6 cursor-pointer items-center text-xs font-medium text-indigo-700 hover:text-indigo-900 dark:text-indigo-300 dark:hover:text-indigo-200"><%= t("pgbus.workflows.signals.payload") %></summary>
+                <pre tabindex="0" class="mt-1 overflow-auto rounded bg-gray-50 p-2 text-xs text-gray-800 dark:bg-gray-900 dark:text-gray-200"><%= JSON.pretty_generate(payload) %></pre>
+              </details>
+            <% end %>
+          </td>
+          <td data-label="<%= t("pgbus.workflows.signals.headers.status") %>" class="px-4 py-3 text-sm"><%= pgbus_workflow_signal_badge(signal[:status]) %></td>
+          <td data-label="<%= t("pgbus.workflows.signals.headers.received") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300"><%= pgbus_time(signal[:created_at]) %></td>
+          <td data-label="<%= t("pgbus.workflows.signals.headers.claimed") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300"><%= pgbus_time(signal[:claimed_at]) %></td>
+          <td data-label="<%= t("pgbus.workflows.signals.headers.consumed") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300"><%= pgbus_time(signal[:consumed_at]) %></td>
+          <td data-label="<%= t("pgbus.workflows.signals.headers.idempotency_key") %>" class="px-4 py-3 font-mono text-xs text-gray-600 dark:text-gray-300"><%= signal[:idempotency_key] || Pgbus::Web::TimeFormat::NONE %></td>
+        </tr>
+      <% end %>
+      <% if @workflow[:signals].empty? %>
+        <%= render "pgbus/shared/empty_row", colspan: 6, message: t("pgbus.workflows.signals.empty") %>
+      <% end %>
+    </tbody>
+  </table>
+</section>

data/app/views/pgbus/workflows/_status_filter.html.erb

@@ -0,0 +1,12 @@
+<%# The status tabs (issue #542): ongoing by default, each state, all. A tab
+    keeps the filters and goes back to page 1. %>
+<nav class="mb-4 flex flex-wrap gap-2" aria-label="<%= t("pgbus.workflows.index.status_label") %>" data-testid="workflow-status-tabs">
+  <% Pgbus::Web::DataSource::WorkflowList::STATUSES.each do |status| %>
+    <% active = status == @query.status %>
+    <a href="<%= pgbus_workflows_path_with(@query, status: status) %>"
+       data-status="<%= status %>" aria-current="<%= active ? "page" : "false" %>"
+       class="inline-flex items-center rounded-md px-3 py-2 text-sm font-medium <%= active ? 'bg-gray-800 text-white dark:bg-gray-700' : 'text-gray-600 hover:bg-gray-100 hover:text-gray-900 dark:text-gray-300 dark:hover:bg-gray-800 dark:hover:text-white' %>">
+      <%= t("pgbus.workflows.tabs.#{status}") %>
+    </a>
+  <% end %>
+</nav>

data/app/views/pgbus/workflows/_steps_table.html.erb

@@ -0,0 +1,79 @@
+<%# Every attempt, newest first (issue #542): the text equivalent of the
+    timeline — the three durations, the worker and app revision, and the
+    error with its backtrace and cause chain under a <details>. %>
+<section class="mb-8 rounded-lg bg-white dark:bg-gray-800 shadow ring-1 ring-gray-200 dark:ring-gray-700" aria-labelledby="workflow-steps-title" data-testid="workflow-steps">
+  <h2 id="workflow-steps-title" class="px-4 py-3 border-b border-gray-200 dark:border-gray-700 text-lg font-medium text-gray-900 dark:text-white"><%= t("pgbus.workflows.steps.title") %></h2>
+  <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.workflows.steps.headers.step") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.steps.headers.status") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.steps.headers.scheduled") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.steps.headers.started") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.steps.headers.finished") %></th>
+        <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.steps.headers.waited") %></th>
+        <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.steps.headers.queued") %></th>
+        <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.steps.headers.ran") %></th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.steps.headers.worker") %></th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+      <% @workflow[:steps].each do |step| %>
+        <% durations = step[:durations] || {} %>
+        <tr data-step-attempt="<%= step[:step_name] %>-<%= step[:attempt] %>" class="align-top hover:bg-gray-50 dark:hover:bg-gray-700/50">
+          <td data-label="<%= t("pgbus.workflows.steps.headers.step") %>" class="px-4 py-3 text-sm text-gray-900 dark:text-white">
+            <code class="font-mono"><%= step[:step_name] %></code>
+            <span class="text-gray-500 dark:text-gray-400">#<%= step[:attempt] %></span>
+            <% if step[:batch_id] %>
+              <span class="block text-xs"><%= pgbus_link_to t("pgbus.workflows.steps.batch", batch: step[:batch_id][0, 8]), pgbus.batch_path(step[:batch_id]), size: :sm %></span>
+            <% end %>
+            <% if step[:wait_for] %>
+              <span class="block text-xs text-gray-600 dark:text-gray-300"><%= t("pgbus.workflows.steps.waits_for_html", signal: tag.code(step[:wait_for], class: "font-mono")) %></span>
+            <% end %>
+          </td>
+          <td data-label="<%= t("pgbus.workflows.steps.headers.status") %>" class="px-4 py-3 text-sm max-w-md">
+            <%= pgbus_workflow_step_badge(step[:status]) %>
+            <% if step[:outcome] && step[:outcome] != step[:status] %>
+              <span class="ml-1 text-xs text-gray-600 dark:text-gray-300"><%= t("pgbus.workflows.outcomes.#{step[:outcome]}", default: step[:outcome].to_s.humanize) %></span>
+            <% end %>
+            <% if step[:error_class] %>
+              <p class="mt-1 font-mono text-xs text-red-700 dark:text-red-300"><%= step[:error_class] %></p>
+              <p class="text-xs text-gray-700 dark:text-gray-300 break-words"><%= step[:error_message] %></p>
+              <% if step[:error_backtrace].present? || step[:error_causes].any? %>
+                <details class="mt-1">
+                  <summary class="inline-flex min-h-6 cursor-pointer items-center text-xs font-medium text-indigo-700 hover:text-indigo-900 dark:text-indigo-300 dark:hover:text-indigo-200"><%= t("pgbus.workflows.steps.show_backtrace") %></summary>
+                  <% if step[:error_backtrace].present? %>
+                    <pre tabindex="0" class="mt-1 max-h-64 overflow-auto rounded bg-gray-50 p-2 text-xs text-gray-800 dark:bg-gray-900 dark:text-gray-200"><%= step[:error_backtrace] %></pre>
+                  <% end %>
+                  <% step[:error_causes].each do |cause| %>
+                    <p class="mt-1 text-xs text-gray-700 dark:text-gray-300"><%= t("pgbus.workflows.steps.caused_by", error: "#{cause["class"]}: #{cause["message"]}") %></p>
+                  <% end %>
+                </details>
+              <% end %>
+            <% end %>
+          </td>
+          <td data-label="<%= t("pgbus.workflows.steps.headers.scheduled") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300"><%= pgbus_time(step[:scheduled_at]) %></td>
+          <td data-label="<%= t("pgbus.workflows.steps.headers.started") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300"><%= pgbus_time(step[:started_at]) %></td>
+          <td data-label="<%= t("pgbus.workflows.steps.headers.finished") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300"><%= pgbus_time(step[:finished_at]) %></td>
+          <td data-label="<%= t("pgbus.workflows.steps.headers.waited") %>" class="px-4 py-3 text-right font-mono text-sm text-gray-700 dark:text-gray-300">
+            <%= pgbus_duration(durations[:waited]) %>
+            <% if durations[:waiting] %>
+              <span class="block text-xs text-gray-600 dark:text-gray-300"><%= t("pgbus.workflows.steps.waiting_for", duration: pgbus_duration(durations[:waiting])) %></span>
+            <% end %>
+          </td>
+          <td data-label="<%= t("pgbus.workflows.steps.headers.queued") %>" class="px-4 py-3 text-right font-mono text-sm text-gray-700 dark:text-gray-300"><%= pgbus_duration(durations[:queued]) %></td>
+          <td data-label="<%= t("pgbus.workflows.steps.headers.ran") %>" class="px-4 py-3 text-right font-mono text-sm text-gray-700 dark:text-gray-300"><%= pgbus_duration(durations[:ran]) %></td>
+          <td data-label="<%= t("pgbus.workflows.steps.headers.worker") %>" class="px-4 py-3 text-xs text-gray-600 dark:text-gray-300">
+            <span class="block font-mono"><%= step[:worker] || Pgbus::Web::TimeFormat::NONE %></span>
+            <% if step[:app_revision] %>
+              <span class="block"><%= t("pgbus.workflows.steps.revision", revision: step[:app_revision]) %></span>
+            <% end %>
+          </td>
+        </tr>
+      <% end %>
+      <% if @workflow[:steps].empty? %>
+        <%= render "pgbus/shared/empty_row", colspan: 9, message: t("pgbus.workflows.steps.empty") %>
+      <% end %>
+    </tbody>
+  </table>
+</section>

data/app/views/pgbus/workflows/_timeline.html.erb

@@ -0,0 +1,49 @@
+<%# The timeline (issue #542): one range-bar row per attempt, split into
+    waited, queued and ran (ran coloured by how the attempt ended), with the
+    waits and pauses as their own segments and a dashed line per missed wait
+    deadline. charts.js renderTimeline draws
+    it from the payload embedded once below; the attempts table under it is
+    the full text alternative. %>
+<% timeline = @workflow[:timeline] %>
+<section class="mb-8 rounded-lg bg-white dark:bg-gray-800 p-4 shadow ring-1 ring-gray-200 dark:ring-gray-700" aria-labelledby="workflow-timeline-title">
+  <h2 id="workflow-timeline-title" class="text-lg font-medium text-gray-900 dark:text-white"><%= t("pgbus.workflows.timeline.title") %></h2>
+  <% if timeline[:rows].empty? %>
+    <p class="py-8 text-center text-sm text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.timeline.empty") %></p>
+  <% else %>
+    <% rows = timeline[:rows].size + (timeline[:paused].any? ? 1 : 0) %>
+    <figure class="mt-3">
+      <div id="workflow-timeline-chart" role="img" aria-label="<%= t("pgbus.workflows.timeline.caption") %>"
+           style="min-height: <%= [160, (rows * 36) + 90].max %>px;"></div>
+      <figcaption class="mt-3 text-sm text-gray-700 dark:text-gray-300"><%= t("pgbus.workflows.timeline.caption") %></figcaption>
+    </figure>
+    <%# The pauses as text: the chart's paused row, for those who cannot see it. %>
+    <% if timeline[:paused].any? %>
+      <ul class="mt-2 space-y-1 text-sm text-gray-700 dark:text-gray-300" data-testid="workflow-pauses">
+        <% timeline[:paused].each do |period| %>
+          <li><%= t("pgbus.workflows.timeline.paused_period_html", from: pgbus_absolute_time(Time.at(period[:from] / 1000.0)),
+                    duration: period[:duration]) %></li>
+        <% end %>
+      </ul>
+    <% end %>
+    <%# The missed wait deadlines as text: the chart's dashed lines (issue #565). %>
+    <% if timeline[:wait_timeouts].any? %>
+      <ul class="mt-2 space-y-1 text-sm text-gray-700 dark:text-gray-300" data-testid="workflow-wait-timeouts">
+        <% timeline[:wait_timeouts].each do |mark| %>
+          <li><%= t("pgbus.workflows.timeline.wait_timeout_html", step: tag.code(mark[:step], class: "font-mono"),
+                    time: pgbus_absolute_time(Time.at(mark[:at] / 1000.0)), action: tag.code(mark[:action], class: "font-mono")) %></li>
+        <% end %>
+      </ul>
+    <% end %>
+    <%# json_escape keeps a value from closing the tag; a data block needs no nonce. %>
+    <%= tag.script(json_escape(timeline.to_json).html_safe, type: "application/json", id: "pgbus-workflow-timeline-data") %> <%# herb:disable erb-no-unsafe-raw %>
+    <script type="module" nonce="<%= content_security_policy_nonce %>">
+      import { renderTimeline, observeThemeChanges } from "charts";
+
+      const i18n = <%= json_escape(pgbus_workflow_chart_i18n.to_json).html_safe %>;
+      const data = JSON.parse(document.getElementById("pgbus-workflow-timeline-data").textContent);
+
+      renderTimeline(data, i18n);
+      observeThemeChanges(() => data, i18n, renderTimeline);
+    </script>
+  <% end %>
+</section>

data/app/views/pgbus/workflows/_workflows_table.html.erb

@@ -0,0 +1,59 @@
+<%# The workflow list (issue #542). Each row says, in words, what the run is
+    doing and what happens next (Web::WorkflowState). Auto-refreshes; the
+    pager keeps the status and the filters. %>
+<turbo-frame id="workflows-list" data-auto-refresh data-turbo-action="advance"
+             data-src="<%= pgbus_workflows_path_with(@query, page: (@page if @page > 1), frame: "list") %>">
+  <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.workflows.headers.workflow") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.headers.subject") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.headers.status") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.headers.current_step") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.headers.started") %></th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.headers.last_activity") %></th>
+        </tr>
+      </thead>
+      <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+        <% @workflows.each do |row| %>
+          <% result = pgbus_workflow_state(row) %>
+          <tr data-workflow-id="<%= row[:workflow_id] %>" data-status="<%= row[:status] %>" class="hover:bg-gray-50 dark:hover:bg-gray-700/50">
+            <td data-label="<%= t("pgbus.workflows.headers.workflow") %>" class="px-4 py-3 text-sm">
+              <div><%= pgbus_link_to row[:workflow_class], pgbus.workflow_path(row[:workflow_id]), data: { turbo_frame: "_top" } %></div>
+              <div class="font-mono text-xs text-gray-500 dark:text-gray-400"><%= row[:workflow_id][0, 8] %></div>
+            </td>
+            <td data-label="<%= t("pgbus.workflows.headers.subject") %>" class="px-4 py-3 text-sm text-gray-700 dark:text-gray-300">
+              <%= pgbus_workflow_subject(row) %>
+            </td>
+            <td data-label="<%= t("pgbus.workflows.headers.status") %>" class="px-4 py-3 max-w-md">
+              <%= pgbus_workflow_badge(result) %>
+              <p class="mt-1 text-xs text-gray-600 dark:text-gray-300"><%= pgbus_workflow_next(row, result) %></p>
+            </td>
+            <td data-label="<%= t("pgbus.workflows.headers.current_step") %>" class="px-4 py-3 text-sm text-gray-700 dark:text-gray-300">
+              <code class="font-mono"><%= row[:current_step] || Pgbus::Web::TimeFormat::NONE %></code>
+              <% if row[:current_attempt].to_i > 1 %>
+                <span class="block text-xs text-gray-500 dark:text-gray-400"><%= t("pgbus.workflows.attempt", attempt: row[:current_attempt]) %></span>
+              <% end %>
+            </td>
+            <td data-label="<%= t("pgbus.workflows.headers.started") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300">
+              <%= pgbus_time(row[:created_at]) %>
+            </td>
+            <td data-label="<%= t("pgbus.workflows.headers.last_activity") %>" class="px-4 py-3 text-sm text-gray-600 dark:text-gray-300">
+              <%= pgbus_time(row[:updated_at]) %>
+            </td>
+          </tr>
+        <% end %>
+        <% if @workflows.empty? %>
+          <%= render "pgbus/shared/empty_row", colspan: 6,
+                message: safe_join([content_tag(:p, t("pgbus.workflows.index.empty_title"), class: "text-lg font-medium"),
+                                    content_tag(:p, t("pgbus.workflows.index.empty_hint"), class: "mt-1")]) %>
+        <% end %>
+      </tbody>
+    </table>
+    <%= render "pgbus/shared/pager", page: @page, per_page: @per_page, shown: @workflows.size,
+          total_count: @workflows_count.total,
+          has_more: @workflows_count.capped? && @workflows.size == @per_page,
+          page_path: ->(n) { pgbus_workflows_path_with(@query, page: n) } %>
+  </div>
+</turbo-frame>