pgbus 0.19.3 → 0.20.0

data/lib/pgbus/mcp/tools/workflow_skip_step_tool.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Skips the step a waiting workflow run waits on (issue #550).
+      # DataSource#skip_workflow_step.
+      class WorkflowSkipStepTool < WriteTool
+        tool_name "pgbus_workflow_skip_step"
+        title "Pgbus Workflow: Skip Step"
+        description verb_description(:skip, "Skip the step a waiting Pgbus::Workflow run waits on (a signal or a fan-out batch).")
+        input_schema(**workflow_input_schema)
+
+        def self.call(workflow_id:, reason:, expected_status: nil, server_context: nil)
+          perform(:skip, workflow_id: workflow_id, reason: reason, expected_status: expected_status,
+                         server_context: server_context) do |data_source, **who|
+            data_source.skip_workflow_step(workflow_id, **who)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflow_stats_tool.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # One workflow class's insights over a window (issue #549): its
+      # pipeline with live counts and step performance, throughput, durations,
+      # funnel and per-revision numbers. Maps to DataSource#workflow_definition,
+      # the dashboard's /pgbus/workflows/definitions/:workflow_class.
+      class WorkflowStatsTool < BaseTool
+        tool_name "pgbus_workflow_stats"
+        title "Pgbus Workflow Stats"
+        description <<~DESC
+          One Pgbus::Workflow class over a window (1h, 24h default, 7d or 30d, capped at workflow_retention). steps, in declaration order (gravestones as kind "removed"; names only the rows hold as declared: false): counts (runs sitting at the step now by run status ready/performing/waiting/paused), run_ms (p50/p95/p99 of finished_at - started_at over completed or failed attempts) and pickup_ms (p50/p95 of scheduled → started), rates (failed: an error was recorded, reattempted, skipped) and outcomes over the sample_size attempts that finished in the window; percentiles over fewer than 20 samples are noisy. Also: started/finished/cancelled, e2e_ms, duration_histogram (finished runs per created → finished range), throughput (runs started/finished/cancelled per bucket_seconds), funnel (of the runs started in the window: reached = runs with a row for the step, stopped = where each run is now by status) and by_revision (the five app revisions that finished an attempt last, newest first, totals and per step).
+        DESC
+
+        input_schema(
+          properties: {
+            workflow_class: { type: "string", description: "The class name, e.g. OrderWorkflow or Billing::OrderWorkflow." },
+            window: { type: "string", enum: Web::WorkflowWindow::CHOICES.keys,
+                      description: "1h, 24h (default), 7d or 30d; capped at workflow_retention." }
+          },
+          required: %w[workflow_class]
+        )
+
+        def self.call(workflow_class:, window: nil, server_context: nil)
+          name = workflow_class.to_s
+          unless Web::DataSource::WorkflowInsights::CLASS_NAME.match?(name)
+            return error_response("#{name.inspect} is not a class name (OrderWorkflow or Billing::OrderWorkflow)")
+          end
+
+          detail = data_source_from(server_context).workflow_definition(name, window: Web::WorkflowWindow.parse(window))
+          return error_response("No workflow class or run named #{name}") unless detail
+
+          json_response(Serialization.serialize(workflow: WorkflowInsightsPayload.row(detail)))
+        rescue Web::WorkflowWindow::Invalid => e
+          error_response(e.message)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflows_attention_tool.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # The dashboard's needs-attention view (issue #542): ongoing runs that
+      # wait on a person, grouped. Maps to DataSource#workflow_attention_groups.
+      class WorkflowsAttentionTool < BaseTool
+        tool_name "pgbus_workflows_attention"
+        title "Pgbus Workflows Needing Attention"
+        description <<~DESC
+          Ongoing Pgbus::Workflow runs that need a person, grouped by (workflow_class, step_name, reason, error_class): reason is paused_error, stalled, paused_manual, overdue (due but not picked up past workflow_stall_threshold) or waiting_overdue (waiting past workflow_waiting_visibility_threshold without a wait_timeout). Each group has its run count, first_seen_at/last_seen_at, the status its runs are in and the actions that status allows; total_runs sums the groups (at most 200 groups, biggest first). workflow_class narrows them to one class. The newest error message is redacted unless the server allows payloads and include_payloads is set.
+        DESC
+
+        input_schema(
+          properties: {
+            workflow_class: { type: "string", description: "Only this class's groups, e.g. OrderWorkflow." },
+            include_payloads: {
+              type: "boolean", description: "Include error messages. Only honored when the server allows payloads."
+            }
+          },
+          required: []
+        )
+
+        def self.call(workflow_class: nil, include_payloads: false, server_context: nil)
+          if workflow_class && !Web::DataSource::WorkflowInsights::CLASS_NAME.match?(workflow_class.to_s)
+            return error_response("#{workflow_class.inspect} is not a class name (OrderWorkflow or Billing::OrderWorkflow)")
+          end
+
+          groups = data_source_from(server_context).workflow_attention_groups(workflow_class: workflow_class&.to_s)
+          allowed = payloads_allowed?(server_context, include_payloads)
+
+          json_response(
+            { groups: groups.map { |group| WorkflowPayloads.group(group, allowed: allowed) },
+              total_runs: groups.sum { |group| group[:count] } },
+            server_context: server_context, include_payloads: include_payloads
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflows_tool.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Workflow runs, filtered like the dashboard's /pgbus/workflows (issue
+      # #542). Maps to DataSource#workflows and #workflows_count; the filters
+      # are checked by the same Web::WorkflowQuery the index uses.
+      class WorkflowsTool < BaseTool
+        tool_name "pgbus_workflows"
+        title "Pgbus Workflows"
+        description <<~DESC
+          List Pgbus::Workflow runs, newest first: class, subject, status, current step and attempt, what a waiting step waits for (signal name, fan-out batch progress), when a scheduled step runs, and the error class of a paused one. status is "ongoing" (default: ready, performing, waiting or paused), one state, or "all"; the other filters combine with AND. created_from/created_to and ended_from/ended_to (when a run finished or was cancelled) take an ISO 8601 date or time. Paginated (default 25, max 100); total is capped at 10000. The error message is redacted unless the server allows payloads and include_payloads is set.
+        DESC
+
+        MAX_PER_PAGE = 100
+        MAX_PAGE = 1_000
+        TEXT = %w[workflow_class step error_class subject_type subject_id workflow_id].freeze
+
+        input_schema(
+          properties: {
+            status: { type: "string", enum: Web::DataSource::WorkflowList::STATUSES,
+                      description: "ongoing (default), ready, performing, waiting, paused, finished, cancelled or all." },
+            **TEXT.to_h { |name| [name.to_sym, { type: "string", description: "Exact #{name.tr("_", " ")}." }] },
+            created_from: { type: "string", description: "Created at or after this ISO 8601 date or time." },
+            created_to: { type: "string", description: "Created at or before this ISO 8601 date (the whole day) or time." },
+            ended_from: { type: "string", description: "Finished or cancelled at or after this ISO 8601 date or time." },
+            ended_to: {
+              type: "string", description: "Finished or cancelled at or before this ISO 8601 date (the whole day) or time."
+            },
+            page: { type: "integer", description: "1-based page number (default 1, max 1000).", minimum: 1 },
+            per_page: { type: "integer", description: "Rows per page (default 25, max 100).", minimum: 1 },
+            include_payloads: {
+              type: "boolean", description: "Include error messages. Only honored when the server allows payloads."
+            }
+          },
+          required: []
+        )
+
+        def self.call(page: 1, per_page: 25, include_payloads: false, server_context: nil, **filters)
+          query = Web::WorkflowQuery.new(filters)
+          data_source = data_source_from(server_context)
+          per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
+          page = page.to_i.clamp(1, MAX_PAGE)
+          rows = data_source.workflows(status: query.status, page: page, per_page: per_page, **query.filters)
+          count = data_source.workflows_count(status: query.status, **query.filters)
+          allowed = payloads_allowed?(server_context, include_payloads)
+
+          json_response(
+            { workflows: rows.map { |row| WorkflowPayloads.row(row, allowed: allowed) }, page: page, per_page: per_page,
+              total: count.total, has_more: more_pages?(count, page: page, per_page: per_page, shown: rows.size) },
+            server_context: server_context, include_payloads: include_payloads
+          )
+        rescue Web::WorkflowQuery::Invalid => e
+          error_response(e.message)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/workflow_insights_payload.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # The workflow insights' hashes as the MCP tools send them (issue #549).
+    # removed_in_flight is keyed by step name, and a step may be named like a
+    # payload key (removed_step :payload), which the Redactor would blank:
+    # the tools send it as [{ step:, runs: }] rows instead.
+    module WorkflowInsightsPayload
+      module_function
+
+      def row(row) = row.merge(removed_in_flight: row.fetch(:removed_in_flight, {}).map { |step, runs| { step: step, runs: runs } })
+    end
+  end
+end

data/lib/pgbus/mcp/workflow_payloads.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # What the workflow tools (issue #542) send back. A run's arguments, its
+    # steps' outputs, its signals' payloads and its error text (message,
+    # backtrace, cause messages, an event's error_message) can carry
+    # application data, and the Redactor only blanks known payload keys
+    # holding a leaf value, so these tools gate them explicitly: replaced by
+    # Redactor::REDACTED unless BaseTool.payloads_allowed? says otherwise.
+    # Written out through MCP::Serialization.
+    module WorkflowPayloads
+      REDACTED = Redactor::REDACTED
+      STEP_SECRETS = %i[output error_message error_backtrace].freeze
+
+      module_function
+
+      def row(row, allowed:)
+        serialize(allowed ? row : row.merge(redact(row, :error_message)))
+      end
+
+      def detail(detail, allowed:)
+        return serialize(detail.except(:timeline)) if allowed
+
+        gated = detail.except(:timeline).merge(arguments: REDACTED, **redact(detail, :error_message))
+        gated[:steps] = Array(detail[:steps]).map { |step| gate_step(step) }
+        gated[:signals] = Array(detail[:signals]).map { |signal| signal.merge(payload: REDACTED) }
+        gated[:events] = Array(detail[:events]).map { |event| gate_event(event) }
+        serialize(gated)
+      end
+
+      def group(group, allowed:)
+        serialize(allowed ? group : group.merge(redact(group, :error_message)))
+      end
+
+      def gate_step(step)
+        gated = step.merge(STEP_SECRETS.to_h { |key| [key, step[key].nil? ? nil : REDACTED] })
+        gated[:error_causes] = Array(step[:error_causes]).map { |cause| cause.slice("class", :class) }
+        gated
+      end
+
+      def gate_event(event)
+        details = event[:details] || {}
+        event.merge(details: details.reject { |key, _| key.to_s == "error_message" })
+      end
+
+      # { key => REDACTED } when the value is there, so a nil stays nil.
+      def redact(hash, key) = hash[key].nil? ? {} : { key => REDACTED }
+
+      def serialize(value) = Serialization.serialize(value)
+    end
+  end
+end

data/lib/pgbus/mcp/write_tool.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # Base class for the opt-in write tools (issue #550). Deliberately not a
+    # BaseTool subclass: no write tool can inherit the read-only annotations,
+    # and no read tool can become a write tool by changing its superclass.
+    # Server registers these only when config.mcp_write_tools is true.
+    #
+    # Every call (#perform): the run loaded (unknown: ok: false), the tool's
+    # inputs and a reason (1-500 characters after trimming) checked,
+    # expected_status checked when given, the verb checked against the run's
+    # available_actions, then the same Web::DataSource action the dashboard
+    # uses, recorded as actor "mcp" (or "mcp:<client name>"). The answer is
+    # { ok:, reason:, workflow: } with the run as it is after the call,
+    # payloads always redacted; a refusal changes nothing and records nothing.
+    #
+    # The two checks read the run before acting, so they are advisory: the
+    # action's guarded transition under the run's row lock decides, and its
+    # code (:not_allowed, with the status the run is in now) is passed on.
+    class WriteTool < ::MCP::Tool
+      ANNOTATIONS = { read_only_hint: false, destructive_hint: true, idempotent_hint: false, open_world_hint: false }.freeze
+      REASON_LIMIT = 500
+      CLIENT_NAME_LIMIT = 100
+      ACTOR = "mcp"
+      # What an unexpected failure answers: its text can carry internals
+      # (hosts, SQL, values), and Web::DataSource has already logged it.
+      FAILED = "the action failed unexpectedly; the error is in the pgbus log"
+
+      annotations(**ANNOTATIONS)
+
+      class << self
+        # MCP::Tool.inherited resets @annotations_value on every subclass, so
+        # fall back to the nearest ancestor's (as BaseTool does).
+        def annotations_value
+          super || (superclass.respond_to?(:annotations_value) ? superclass.annotations_value : nil)
+        end
+
+        # For a verb whose repeat can never act again (cancel: a cancelled run
+        # stays cancelled). Not skip or resume at: a retry can act again once
+        # the run has parked or paused again.
+        def idempotent!
+          annotations(**ANNOTATIONS, idempotent_hint: true)
+        end
+
+        # The input_schema every write tool takes, plus the tool's own fields.
+        def workflow_input_schema(properties: {}, required: [])
+          {
+            properties: {
+              workflow_id: { type: "string", description: "The run's workflow_id (a UUID)." },
+              reason: { type: "string", minLength: 1, maxLength: REASON_LIMIT,
+                        description: "Why, in 1-#{REASON_LIMIT} characters. Recorded on the run's audit trail." },
+              expected_status: {
+                type: "string", enum: Workflow::States::WORKFLOW,
+                description: "The status you read. If the run is in another one when the call starts: ok: false, nothing done."
+              },
+              **properties
+            },
+            required: %w[workflow_id reason] + required
+          }
+        end
+
+        # The tool description: what it does, the transition it makes, and the
+        # opt-in. Frozen: it is class state (the conformance audit checks).
+        def verb_description(verb, summary)
+          transition = Workflow::States.fetch(verb)
+          <<~DESC.freeze
+            #{summary} Allowed from: #{transition.from.join(", ")}. What happens: #{transition.effect}. A write tool: it exists only when the server was built with config.mcp_write_tools = true. reason is required and recorded on the run's audit trail with actor "mcp" (or "mcp:<client name>" when the transport knows the client); pass expected_status (the status you read with pgbus_workflow): a run that has moved on by the time the call starts answers ok: false and nothing is done (the check runs just before the action, whose transition is guarded again under the run's row lock). Answers { ok, reason, workflow } with the run as it is after the call; a refused call changes nothing and records nothing (a transition refused under the lock adds code and status, a disallowed verb available_actions); arguments, outputs, signal payloads and error text are redacted.
+          DESC
+        end
+
+        # Runs the checks, then yields (data_source, actor:, reason:) for the
+        # DataSource action, whose { ok:, ... } becomes the answer. +invalid+
+        # is the tool's own input refusal (a blank step, an oversized
+        # payload), answered like every other refusal: with the run as it is.
+        def perform(verb, workflow_id:, reason:, expected_status:, server_context:, invalid: nil)
+          data_source = BaseTool.data_source_from(server_context)
+          detail = data_source.workflow_detail(workflow_id)
+          return answer(ok: false, reason: "workflow #{workflow_id} not found", workflow: nil) unless detail
+
+          note = reason.to_s.strip
+          refusal = input_refusal(note, invalid) || guard_refusal(verb, detail, expected_status)
+          return answer(**refusal, workflow: present(detail)) if refusal
+
+          result = outcome(yield(data_source, actor: actor(server_context), reason: note))
+          answer(**result, workflow: present(data_source.workflow_detail(workflow_id)))
+        end
+
+        def answer(**value) = BaseTool.json_response(value)
+
+        private
+
+        def input_refusal(note, invalid)
+          unless note.length.between?(1, REASON_LIMIT)
+            return { ok: false, reason: "reason must be 1-#{REASON_LIMIT} characters after trimming whitespace" }
+          end
+
+          { ok: false, reason: invalid } if invalid
+        end
+
+        # The DataSource action's answer, ok and reason first; an unexpected
+        # failure's text replaced (FAILED).
+        def outcome(result)
+          reason = result[:code] == :failed ? FAILED : result[:reason]
+          { ok: result[:ok], reason: reason, **result.except(:ok, :reason) }
+        end
+
+        def guard_refusal(verb, detail, expected_status)
+          status = detail[:status].to_s
+          if expected_status && expected_status.to_s != status
+            return { ok: false, reason: "workflow #{detail[:workflow_id]} is #{status}, not #{expected_status}" }
+          end
+
+          allowed = Array(detail[:available_actions]).map(&:to_s)
+          return if allowed.include?(verb.to_s)
+
+          { ok: false, reason: "cannot #{verb.to_s.tr("_", " ")} a #{status} workflow", available_actions: allowed }
+        end
+
+        def present(detail) = detail && WorkflowPayloads.detail(detail, allowed: false)
+
+        # "mcp", or "mcp:<name>" when the transport knows the client (an
+        # MCP::ServerContext on mcp >= 1.x; a plain Hash context has none).
+        # The name is client-supplied: control characters dropped, length capped.
+        def actor(server_context)
+          info = server_context.client_info if server_context.respond_to?(:client_info)
+          name = info.is_a?(Hash) ? (info[:name] || info["name"]) : nil
+          name = name.to_s.gsub(/[^[:print:]]/, "").strip[0, CLIENT_NAME_LIMIT]
+          name.empty? ? ACTOR : "#{ACTOR}:#{name}"
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp.rb

@@ -14,6 +14,7 @@ module Pgbus
     REQUIRES = %w[
       pgbus/mcp/redactor
       pgbus/mcp/base_tool
+      pgbus/mcp/serialization
       pgbus/mcp/health_analyzer
       pgbus/mcp/tools/health_tool
       pgbus/mcp/tools/queues_tool
@@ -29,6 +30,20 @@ module Pgbus
       pgbus/mcp/tools/stats_tool
       pgbus/mcp/tools/recurring_tool
       pgbus/mcp/tools/deploy_tasks_tool
+      pgbus/mcp/workflow_payloads
+      pgbus/mcp/tools/workflows_tool
+      pgbus/mcp/tools/workflow_detail_tool
+      pgbus/mcp/tools/workflows_attention_tool
+      pgbus/mcp/workflow_insights_payload
+      pgbus/mcp/tools/workflow_definitions_tool
+      pgbus/mcp/tools/workflow_stats_tool
+      pgbus/mcp/write_tool
+      pgbus/mcp/tools/workflow_resume_tool
+      pgbus/mcp/tools/workflow_cancel_tool
+      pgbus/mcp/tools/workflow_skip_step_tool
+      pgbus/mcp/tools/workflow_resume_at_tool
+      pgbus/mcp/tools/workflow_run_now_tool
+      pgbus/mcp/tools/workflow_signal_tool
       pgbus/mcp/server
       pgbus/mcp/runner
       pgbus/mcp/rack_app

data/lib/pgbus/metrics/backends/statsd.rb

@@ -11,6 +11,10 @@ module Pgbus
       #   gauge     -> "name:value|g"
       #   histogram -> "name:value|ms"
       #
+      # StatsD reads |ms values as milliseconds, so a histogram named
+      # *_seconds (the Prometheus convention, e.g.
+      # pgbus_workflow_step_duration_seconds) is sent as *_ms, times 1000.
+      #
       # Tags are appended as DogStatsD `|#k:v,k:v`. No gem dependency — a plain
       # UDPSocket. UDP send is fire-and-forget; any socket error is logged and
       # swallowed so a metrics hiccup never propagates into the producer thread.
@@ -32,6 +36,8 @@ module Pgbus
         end
 
         def histogram(name, value, tags = {})
+          return emit("#{name.delete_suffix("_seconds")}_ms", value * 1000.0, "ms", tags) if name.end_with?("_seconds")
+
           emit(name, value, "ms", tags)
         end
 

data/lib/pgbus/metrics/subscriber.rb

@@ -73,7 +73,8 @@ module Pgbus
             subscribe("pgbus.recurring.enqueue") { |event| on_recurring_enqueue(event) },
             subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) },
             subscribe("pgbus.consumer.recycle") { |event| on_consumer_recycle(event) },
-            subscribe("pgbus.client.pool") { |event| on_client_pool(event) }
+            subscribe("pgbus.client.pool") { |event| on_client_pool(event) },
+            *WorkflowMetrics::EVENTS.map { |name| subscribe(name) { |event| on_workflow(event) } }
           ].freeze
         end
 
@@ -251,6 +252,18 @@ module Pgbus
           backend.gauge("#{METRIC_PREFIX}pool_available", payload[:available], tags)
         end
 
+        # ── Workflows (issue #540) ────────────────────────────────────────
+
+        def on_workflow(event)
+          WorkflowMetrics.samples(event.name, event.payload).each do |kind, name, value, tags|
+            case kind
+            when :histogram then backend.histogram(name, value, tags)
+            when :counter then backend.increment(name, value, tags)
+            when :gauge then backend.gauge(name, value, tags)
+            end
+          end
+        end
+
         def hostname
           Socket.gethostname
         end

data/lib/pgbus/metrics/workflow_metrics.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Metrics
+    # The pgbus.workflow.* event → metric mapping (issue #540), shared by
+    # Metrics::Subscriber (Prometheus, StatsD) and the AppSignal subscriber so
+    # both backends report the same names and labels:
+    #
+    #   pgbus_workflow_step_duration_seconds{workflow_class, step, outcome}  histogram
+    #   pgbus_workflow_steps_total{workflow_class, step, outcome}            counter
+    #   pgbus_workflows_finished_total{workflow_class}                       counter
+    #   pgbus_workflows_paused_total{workflow_class, error_class}            counter (error_class absent for a manual pause)
+    #   pgbus_workflows_cancelled_total{workflow_class}                      counter
+    #   pgbus_workflow_stalls_total{workflow_class, step, detection}         counter (detection: redelivery | sweep)
+    #   pgbus_workflows{workflow_class, status}                              gauge, from each sweep
+    #   pgbus_workflows_stuck{workflow_class, reason}                        gauge, from each sweep
+    #
+    # Label values come from code (class, step and exception names), so
+    # their cardinality is bounded; workflow ids never become labels.
+    module WorkflowMetrics
+      EVENTS = %w[
+        pgbus.workflow.step pgbus.workflow_finished pgbus.workflow_paused pgbus.workflow_cancelled
+        pgbus.workflow.stall_detected pgbus.workflow.gauge
+      ].freeze
+
+      module_function
+
+      # [[kind, name, value, tags], ...] for one event; kind is :histogram,
+      # :counter or :gauge.
+      def samples(event_name, payload)
+        klass = payload[:workflow_class]
+        case event_name
+        when "pgbus.workflow.step" then step_samples(klass, payload)
+        when "pgbus.workflow_finished" then [counter("pgbus_workflows_finished_total", workflow_class: klass)]
+        when "pgbus.workflow_paused"
+          [counter("pgbus_workflows_paused_total", workflow_class: klass, error_class: payload[:error_class])]
+        when "pgbus.workflow_cancelled" then [counter("pgbus_workflows_cancelled_total", workflow_class: klass)]
+        when "pgbus.workflow.stall_detected"
+          [counter("pgbus_workflow_stalls_total", workflow_class: klass, step: payload[:step_name], detection: payload[:detection])]
+        when "pgbus.workflow.gauge" then gauge_samples(payload)
+        else []
+        end
+      end
+
+      def step_samples(klass, payload)
+        tags = { workflow_class: klass, step: payload[:step_name], outcome: payload[:outcome] }.compact
+        samples = [[:counter, "pgbus_workflow_steps_total", 1, tags]]
+        samples.unshift([:histogram, "pgbus_workflow_step_duration_seconds", payload[:duration], tags]) if payload[:duration]
+        samples
+      end
+
+      def gauge_samples(payload)
+        statuses = Array(payload[:statuses]).map do |row|
+          [:gauge, "pgbus_workflows", row[:count], { workflow_class: row[:workflow_class], status: row[:status] }]
+        end
+        stuck = Array(payload[:stuck]).map do |row|
+          [:gauge, "pgbus_workflows_stuck", row[:count], { workflow_class: row[:workflow_class], reason: row[:reason] }]
+        end
+        statuses + stuck
+      end
+
+      def counter(name, **tags) = [:counter, name, 1, tags.compact]
+    end
+  end
+end

data/lib/pgbus/process/dispatcher.rb

@@ -19,6 +19,7 @@ module Pgbus
       JOB_LOCK_CLEANUP_INTERVAL = 300 # Run job lock cleanup every 5 minutes
       STATS_CLEANUP_INTERVAL = 3600 # Run stats cleanup every hour
       ORPHAN_STREAM_SWEEP_INTERVAL = 3600 # Run orphan stream sweep every hour
+      WORKFLOW_CLEANUP_INTERVAL = 3600 # Delete finished/cancelled workflows past workflow_retention every hour
       TABLE_MAINTENANCE_INTERVAL = Pgbus::TableMaintenance::MAINTENANCE_INTERVAL
 
       # Page size for archive compaction. Each cycle deletes up to this
@@ -57,6 +58,7 @@ module Pgbus
         @last_stream_archive_compaction_at
         @last_outbox_cleanup_at @last_job_lock_cleanup_at @last_stats_cleanup_at
         @last_orphan_stream_sweep_at @last_table_maintenance_at
+        @last_workflow_sweep_at @last_workflow_cleanup_at
       ].freeze
 
       # Outcome of a single maintenance task in a cycle. Lets run_maintenance
@@ -247,6 +249,8 @@ module Pgbus
         sweep_interval = config.streams_orphan_sweep_interval
         results << run_if_due(now, :@last_orphan_stream_sweep_at, sweep_interval) { sweep_orphan_streams } if sweep_interval
         results << run_if_due(now, :@last_table_maintenance_at, TABLE_MAINTENANCE_INTERVAL) { run_table_maintenance }
+        results << run_if_due(now, :@last_workflow_sweep_at, config.workflow_sweep_interval) { sweep_workflows }
+        results << run_if_due(now, :@last_workflow_cleanup_at, WORKFLOW_CLEANUP_INTERVAL) { cleanup_workflows }
         results
       end
 
@@ -388,6 +392,28 @@ module Pgbus
         e
       end
 
+      # Stalled and overdue workflow steps, timed-out waits, and the workflow gauges.
+      def sweep_workflows
+        summary = Workflow::Sweep.repair(config: config)
+        return unless summary && summary.values_at(:stalled, :resent, :timed_out, :fan_outs).compact.any?(&:positive?)
+
+        Pgbus.logger.info do
+          "[Pgbus] Workflow sweep: #{summary[:stalled]} stalled step(s) repaired, #{summary[:resent]} overdue step(s) re-sent, " \
+            "#{summary[:timed_out].to_i} wait(s) timed out, #{summary[:fan_outs].to_i} fan-out(s) resolved"
+        end
+      rescue StandardError => e
+        log_maintenance_failure("Workflow sweep", e)
+        e
+      end
+
+      def cleanup_workflows
+        deleted = Workflow::Sweep.cleanup(retention: config.workflow_retention)
+        Pgbus.logger.debug { "[Pgbus] Cleaned up #{deleted} finished workflows" } if deleted.positive?
+      rescue StandardError => e
+        log_maintenance_failure("Workflow cleanup", e)
+        e
+      end
+
       def cleanup_stats
         retention = config.stats_retention
         return unless retention&.positive?

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.19.3"
+  VERSION = "0.20.0"
 end