pgbus 0.19.4 → 0.20.1

data/lib/pgbus/configuration/workflow_settings.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Configuration
+    # Workflows (issue #540): durable multi-step Pgbus::Workflow runs.
+    #
+    #   config.workflow_queue = "workflows"             # where StepJob messages go
+    #   config.workflow_retention = 30.days             # finished/cancelled runs kept this long; nil keeps them
+    #   config.workflow_sweep_interval = 5.minutes      # how often the dispatcher repairs stuck steps
+    #   config.workflow_stall_threshold = 1.hour        # an in_progress step older than this is stalled
+    #   config.workflow_stall_action = :pause           # :pause, :reattempt or :cancel a stalled step
+    #   config.workflow_max_payload_size = 131_072      # bytes: arguments and step outputs
+    #   config.workflow_error_backtrace_lines = 50      # backtrace lines kept on a failed step
+    #   config.workflow_waiting_visibility_threshold = 7.days # a step waiting this long without a
+    #                                                   # wait_timeout: counts as stuck (waiting_overdue)
+    #   config.workflow_subject_url = ->(type, id) { "/admin/#{type.underscore.pluralize}/#{id}" }
+    #                                                   # the dashboard's subject link (nil: plain text)
+    module WorkflowSettings
+      WORKFLOW_STALL_ACTIONS = %i[pause reattempt cancel].freeze
+
+      attr_reader :workflow_queue, :workflow_retention, :workflow_sweep_interval, :workflow_stall_threshold,
+                  :workflow_stall_action, :workflow_waiting_visibility_threshold
+      attr_accessor :workflow_max_payload_size, :workflow_error_backtrace_lines, :workflow_subject_url
+
+      def workflow_queue=(value)
+        name = value.to_s
+        raise Pgbus::ConfigurationError, "workflow_queue must be a non-empty queue name" if value.nil? || name.strip.empty?
+
+        @workflow_queue = name
+      end
+
+      def workflow_retention=(value)
+        @workflow_retention = coerce_duration!(value, :workflow_retention)
+      end
+
+      def workflow_sweep_interval=(value)
+        @workflow_sweep_interval = coerce_duration!(value, :workflow_sweep_interval)
+      end
+
+      def workflow_stall_threshold=(value)
+        @workflow_stall_threshold = coerce_duration!(value, :workflow_stall_threshold)
+      end
+
+      def workflow_waiting_visibility_threshold=(value)
+        @workflow_waiting_visibility_threshold = coerce_duration!(value, :workflow_waiting_visibility_threshold)
+      end
+
+      def workflow_stall_action=(value)
+        action = value.respond_to?(:to_sym) ? value.to_sym : value
+        unless WORKFLOW_STALL_ACTIONS.include?(action)
+          raise Pgbus::ConfigurationError,
+                "workflow_stall_action must be one of #{WORKFLOW_STALL_ACTIONS.map(&:inspect).join(", ")}, got #{value.inspect}"
+        end
+
+        @workflow_stall_action = action
+      end
+
+      private
+
+      def initialize_workflow_settings
+        @workflow_queue = "default"
+        @workflow_retention = 30 * 24 * 3600 # 30 days
+        @workflow_sweep_interval = 300 # 5 minutes
+        @workflow_stall_threshold = 3600 # 1 hour
+        @workflow_stall_action = :pause
+        @workflow_max_payload_size = 131_072 # 128 KB
+        @workflow_error_backtrace_lines = 50
+        @workflow_waiting_visibility_threshold = 7 * 24 * 3600 # 7 days
+        @workflow_subject_url = nil
+      end
+
+      def validate_workflow_settings!
+        { workflow_sweep_interval: workflow_sweep_interval, workflow_stall_threshold: workflow_stall_threshold,
+          workflow_waiting_visibility_threshold: workflow_waiting_visibility_threshold,
+          workflow_retention: workflow_retention }.each do |name, value|
+          next if value.nil? && name == :workflow_retention
+          next if value.is_a?(Numeric) && value.positive? && value.finite?
+
+          raise Pgbus::ConfigurationError, "#{name} must be a finite number of seconds > 0"
+        end
+
+        begin
+          QueueNameValidator.validate!(queue_name(workflow_queue))
+        rescue ArgumentError => e
+          raise Pgbus::ConfigurationError, "workflow_queue #{workflow_queue.inspect}: #{e.message}"
+        end
+
+        { workflow_max_payload_size: workflow_max_payload_size,
+          workflow_error_backtrace_lines: workflow_error_backtrace_lines }.each do |name, value|
+          raise Pgbus::ConfigurationError, "#{name} must be a positive integer" unless value.is_a?(Integer) && value.positive?
+        end
+
+        return if workflow_subject_url.nil? || workflow_subject_url.respond_to?(:call)
+
+        raise Pgbus::ConfigurationError, "workflow_subject_url must respond to #call (a Proc/lambda) or be nil"
+      end
+    end
+  end
+end

data/lib/pgbus/configuration.rb

@@ -7,12 +7,14 @@ module Pgbus
     include PresenceSettings
     include StreamAuthorization
     include DeploySettings
+    include WorkflowSettings
 
     # Connection settings
     attr_accessor :database_url, :connection_params, :pool_size, :pool_timeout
 
     # Queue settings
-    attr_accessor :default_queue, :queue_prefix
+    attr_accessor :default_queue
+    attr_reader :queue_prefix # rubocop:disable Style/AccessorGrouping -- the writer normalizes (see queue_prefix=)
 
     # Worker settings
     attr_accessor :polling_interval, :prefetch_limit, :execution_mode
@@ -215,10 +217,16 @@ module Pgbus
 
     # Web dashboard
     attr_accessor :web_auth, :web_refresh_interval, :web_per_page, :web_live_updates, :web_data_source,
-                  :insights_default_minutes, :base_controller_class, :return_to_app_url,
+                  :insights_default_minutes, :base_controller_class, :return_to_app_url, :web_actor,
                   :metrics_enabled,
                   :web_filter_parameters, :web_filter_sensitive
 
+    # The MCP server's workflow write tools (issue #550): pgbus_workflow_resume,
+    # _cancel, _skip_step, _resume_at, _run_now and _signal. Off by default, and
+    # then they are never built, so tools/list cannot show them. Read once, when
+    # Pgbus::MCP::Server.build runs (pgbus mcp, Pgbus::MCP.rack_app).
+    attr_accessor :mcp_write_tools
+
     # HTTP health endpoints (liveness/readiness for orchestrators like
     # Kubernetes). `health_port` nil (default) leaves the standalone server in
     # the supervisor disabled — mount Pgbus::Web::HealthApp in the host Rails
@@ -365,6 +373,7 @@ module Pgbus
       @recurring_enabled = true
       @recurring_execution_retention = 7 * 24 * 3600 # 7 days
       initialize_deploy_settings
+      initialize_workflow_settings
 
       @zombie_detection = true
 
@@ -380,7 +389,13 @@ module Pgbus
       @require_primary = false
       @connection_guc_mode = :options
 
+      @mcp_write_tools = false
+
       @web_auth = nil
+      # ->(request) { String or nil }: who an operator action on the dashboard
+      # is recorded as ("dashboard:<name>"; nil → "dashboard"). web_auth only
+      # answers allow/deny, so the name comes from here.
+      @web_actor = nil
       @web_refresh_interval = 5000
       @web_per_page = 25
       @web_live_updates = true
@@ -583,6 +598,25 @@ module Pgbus
       @finalized = false
     end
 
+    # Stored the way the queue tables spell it ("my-app" → "my_app"). Table
+    # names are unchanged (queue_name normalizes the joined name the same
+    # way), but code that strips the prefix off a table name to get its queue
+    # back (the dashboard, the worker, a job's uniqueness lock queue) then
+    # finds it. A value normalize cannot spell (nothing table-safe left, or
+    # too long) is kept as given, as before: validate! rejects one that is
+    # too long, and queue_name drops one with nothing table-safe in it.
+    def queue_prefix=(value)
+      @queue_prefix = if value.is_a?(String) && !value.empty?
+                        begin
+                          QueueNameValidator.normalize(value)
+                        rescue ArgumentError
+                          value
+                        end
+                      else
+                        value
+                      end
+    end
+
     def queue_name(name)
       full = "#{queue_prefix}_#{name}"
       QueueNameValidator.normalize(full)
@@ -941,12 +975,14 @@ module Pgbus
       end
 
       raise Pgbus::ConfigurationError, "require_primary must be true or false" unless [true, false].include?(require_primary)
+      raise Pgbus::ConfigurationError, "mcp_write_tools must be true or false" unless [true, false].include?(mcp_write_tools)
 
       validate_job_path_gaps!
       validate_streams!
       validate_metrics_backend!
       validate_fair_share!
       validate_deploy_settings!
+      validate_workflow_settings!
 
       self
     end
@@ -986,6 +1022,27 @@ module Pgbus
       raise Pgbus::ConfigurationError, "capsule processes must be a positive Integer (got #{value.inspect})"
     end
 
+    # A prefix with a leading, trailing or doubled underscore is kept as
+    # written (its tables already exist under it), but queue_name collapses
+    # the separator after it only for a queue name that needs normalizing:
+    # "myapp_" gives myapp__orders yet myapp_orders_handler for
+    # "orders-handler". A job's own release and the dashboard derive the same
+    # lock queue for it and still match, but the reaper cannot resolve that
+    # name back to the table, so a lock orphaned there is never reclaimed and
+    # has to be released by key. Legal, but warned.
+    def warn_queue_prefix_underscores
+      return unless queue_prefix.match?(/\A_|_\z|__/)
+
+      suggested = queue_prefix.squeeze("_").delete_prefix("_").delete_suffix("_")
+      suggestion = suggested.empty? ? "" : "; prefer #{suggested.inspect} for new deployments"
+      Pgbus.logger.warn do
+        "[Pgbus] queue_prefix #{queue_prefix.inspect} has a leading, trailing or doubled underscore — a queue " \
+          "whose name needs normalizing (\"orders-handler\") gets a table spelled unlike its queue, so the " \
+          "reaper cannot find that table: a uniqueness lock orphaned there (a worker crash before its release) " \
+          "is never reclaimed and has to be released by key#{suggestion}"
+      end
+    end
+
     # Buffered claims are kept invisible only by the visibility heartbeat.
     # Without it a message buffered longer than visibility_timeout can be
     # claimed by another worker while it still waits here. Legal, but warned.
@@ -1059,11 +1116,14 @@ module Pgbus
       { queue_prefix: queue_prefix, default_queue: default_queue }.each do |name, value|
         raise Pgbus::ConfigurationError, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
       end
+      warn_queue_prefix_underscores
 
       # web_auth gates the dashboard; a non-callable value silently leaves it
       # open (mirror streams_presence_member).
-      unless web_auth.nil? || web_auth.respond_to?(:call)
-        raise Pgbus::ConfigurationError, "web_auth must respond to #call (a Proc/lambda) or be nil"
+      { web_auth: web_auth, web_actor: web_actor }.each do |name, value|
+        next if value.nil? || value.respond_to?(:call)
+
+        raise Pgbus::ConfigurationError, "#{name} must respond to #call (a Proc/lambda) or be nil"
       end
 
       raise Pgbus::ConfigurationError, "error_reporters must be an Array" unless error_reporters.is_a?(Array)

data/lib/pgbus/dead_letter_header.rb

@@ -30,7 +30,13 @@ module Pgbus
 
     # error: FailedEventRecorder.last_error's Hash, or nil when no failure
     # was recorded. Returns the merged headers as a JSON string.
-    def build(existing:, reason:, source:, source_queue:, attempts:, max_retries:, error: nil, now: Time.now.utc)
+    # source_msg_id / source_enqueued_at: the message's id in source_queue and
+    # when it was sent (the copy gets a new id and enqueued_at in the DLQ).
+    # A discard of the copy uses both to release only the uniqueness lock the
+    # original still holds: bound to it, or unbound and acquired before its
+    # send, never a lock it handed to a retry after (issue #564).
+    def build(existing:, reason:, source:, source_queue:, attempts:, max_retries:, error: nil, source_msg_id: nil,
+              source_enqueued_at: nil, now: Time.now.utc)
       headers = decode(existing, warn: true)
       retries = count(headers.delete(RETRIES_KEY))
       block = {
@@ -42,6 +48,8 @@ module Pgbus
         "max_retries" => max_retries,
         "dead_lettered_at" => iso(now)
       }
+      block["source_msg_id"] = source_msg_id if source_msg_id
+      block["source_enqueued_at"] = iso(source_enqueued_at) if source_enqueued_at
       block["retries_from_dlq"] = retries if retries.positive?
       block.merge!(error_fields(error)) if error
       JSON.generate(headers.merge(KEY => block))

data/lib/pgbus/generators/migration_detector.rb

@@ -57,6 +57,22 @@ module Pgbus
         pgbus_batches
       ].freeze
 
+      # The three tables pgbus:add_workflows creates (issue #540).
+      WORKFLOW_TABLES = %w[pgbus_workflows pgbus_workflow_steps pgbus_workflow_events].freeze
+
+      # The waiting-step columns pgbus:add_workflow_signals adds to
+      # pgbus_workflow_steps (issue #541), with the pgbus_workflow_signals table.
+      WORKFLOW_WAITING_COLUMNS = %w[batch_id wait_for signal_id waiting_since timeout_at].freeze
+      WORKFLOW_WAITING_INDEXES = Ractor.make_shareable(
+        [
+          %w[pgbus_workflow_steps idx_pgbus_workflow_steps_batch],
+          %w[pgbus_workflow_steps idx_pgbus_workflow_steps_timeout],
+          %w[pgbus_workflow_signals idx_pgbus_workflow_signals_idempotency],
+          %w[pgbus_workflow_signals idx_pgbus_workflow_signals_pending],
+          %w[pgbus_workflow_signals idx_pgbus_workflow_signals_claimed]
+        ]
+      )
+
       # generator_key → Rails generator name. Passed to Thor's invoke.
       #
       # Note: uniqueness_keys invokes add_uniqueness_keys, which only
@@ -78,6 +94,8 @@ module Pgbus
         add_outbox: "pgbus:add_outbox",
         add_recurring: "pgbus:add_recurring",
         add_deploy_tasks: "pgbus:add_deploy_tasks",
+        add_workflows: "pgbus:add_workflows",
+        add_workflow_signals: "pgbus:add_workflow_signals",
         add_failed_events_index: "pgbus:add_failed_events_index",
         add_processed_event_completion: "pgbus:add_processed_event_completion",
         add_batch_executions: "pgbus:add_batch_executions",
@@ -101,6 +119,8 @@ module Pgbus
         add_outbox: "outbox entries table (transactional outbox)",
         add_recurring: "recurring tasks + executions tables",
         add_deploy_tasks: "deploy tasks + runs tables (one-time jobs run after a rollover)",
+        add_workflows: "workflow tables (durable multi-step workflows: runs, step attempts, audit trail)",
+        add_workflow_signals: "waiting workflow steps (fan_out, wait_for: signals, wait timeouts)",
         add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)",
         add_processed_event_completion: "completed_at on pgbus_processed_events (two-phase idempotency claim)",
         add_batch_executions: "batch execution-row tracking (self-healing completion, on_failure rename)",
@@ -130,6 +150,7 @@ module Pgbus
           *outbox_migrations,
           *recurring_migrations,
           *deploy_tasks_migrations,
+          *workflows_migrations,
           *failed_events_index_migrations,
           *processed_event_completion_migrations,
           *batch_executions_migrations,
@@ -226,6 +247,25 @@ module Pgbus
         [:add_deploy_tasks]
       end
 
+      # The add_workflows template uses if_not_exists throughout, so a
+      # half-present set of the three tables is safe to queue again.
+      #
+      # add_workflows carries the waiting-step schema too, so a database with
+      # no steps table needs only that one; a steps table without the columns
+      # (or a missing signals table) predates waiting steps.
+      def workflows_migrations
+        migrations = []
+        migrations << :add_workflows unless WORKFLOW_TABLES.all? { |table| table_exists?(table) }
+        return migrations unless table_exists?("pgbus_workflow_steps")
+
+        columns = column_names("pgbus_workflow_steps")
+        waiting = WORKFLOW_WAITING_COLUMNS.all? { |column| columns.include?(column) } &&
+                  table_exists?("pgbus_workflow_signals") &&
+                  WORKFLOW_WAITING_INDEXES.all? { |table, index| index_exists?(table, index) }
+        migrations << :add_workflow_signals unless waiting
+        migrations
+      end
+
       def failed_events_index_migrations
         # pgbus_failed_events is created by pgbus:install, but the
         # unique (queue_name, msg_id) index was added later via its own

data/lib/pgbus/instrumentation.rb

@@ -54,6 +54,39 @@ module Pgbus
   #   pgbus.batch_sweep            — dispatcher stalled-batch sweep
   #                                  payload: stalled_for, stale_executions, orphan_rows,
   #                                  started_batches, finished_batches
+  #   pgbus.workflow.step          — a workflow step attempt ended (body, guard, stall)
+  #                                  payload: workflow_class, workflow_id, step_name, attempt,
+  #                                  outcome (completed | reattempted | skipped | paused |
+  #                                  cancelled | finished_early), status (the step row's),
+  #                                  error_class (nil without an error), duration (seconds
+  #                                  the body ran; 0.0 for a guard; nil for a stall),
+  #                                  pickup_latency (seconds from scheduled_at to the claim)
+  #   pgbus.workflow_finished      — a workflow run finished
+  #                                  payload: workflow_class, workflow_id
+  #   pgbus.workflow_paused        — a workflow run paused (an exception, a stall, pause!)
+  #                                  payload: workflow_class, workflow_id, step_name,
+  #                                  error_class (nil for a manual pause)
+  #   pgbus.workflow_cancelled     — a workflow run was cancelled
+  #                                  payload: workflow_class, workflow_id, step_name
+  #   pgbus.workflow.stall_detected — a step was stalled on the redelivery of the message that
+  #                                  claimed it (detection: "redelivery": its worker died, or
+  #                                  its heartbeat lapsed) or after it outlived its stall_at
+  #                                  (detection: "sweep")
+  #                                  payload: workflow_class, workflow_id, step_name, attempt,
+  #                                  detection
+  #   pgbus.workflow.signal        — signal! stored a signal on a run (or found it stored:
+  #                                  a redelivery with the same idempotency key)
+  #                                  payload: workflow_class, workflow_id, name, duplicate,
+  #                                  woke (true when it woke the step waiting for it)
+  #   pgbus.workflow.wait_timed_out — a waiting step's wait_timeout: passed; its on_timeout
+  #                                  applied (the sweep, or TestHelpers#expire_wait); under
+  #                                  notify the step keeps waiting, once per sweep that finds it late
+  #                                  payload: workflow_class, workflow_id, step_name, attempt,
+  #                                  action (pause! | cancel! | skip! | run | notify)
+  #   pgbus.workflow.gauge         — emitted by each dispatcher workflow sweep
+  #                                  payload: statuses ([{ workflow_class:, status:, count: }]),
+  #                                  stuck ([{ workflow_class:, reason:, count: }]), zero-filled
+  #                                  across every known class; reasons include waiting_overdue
   #
   module Instrumentation
     module_function

data/lib/pgbus/integrations/appsignal/dashboard.json

@@ -4,7 +4,7 @@
   ],
   "dashboard": {
     "title": "Pgbus",
-    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\n",
+    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\nWorkflow step outcomes and run times, stuck workflows and late waits.\n",
     "visuals": [
       {
         "type": "timeseries",
@@ -393,6 +393,162 @@
             "tags": []
           }
         ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Workflow steps per outcome",
+        "description": "Workflow step attempts by class, step and outcome (completed, reattempted, skipped, paused, cancelled, finished_early).",
+        "line_label": "%workflow_class% - %step% - %outcome%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflow_steps_total",
+            "fields": [
+              {
+                "field": "COUNTER"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "step",
+                "value": "*"
+              },
+              {
+                "key": "outcome",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Workflow step run time (seconds)",
+        "description": "Mean and p95 run time of each workflow step's body, in seconds.",
+        "line_label": "%workflow_class% - %step% - %outcome%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflow_step_duration_seconds",
+            "fields": [
+              {
+                "field": "MEAN"
+              },
+              {
+                "field": "P95"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "step",
+                "value": "*"
+              },
+              {
+                "key": "outcome",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Workflows by status",
+        "description": "Workflow runs per class and status, from each dispatcher sweep.",
+        "line_label": "%workflow_class% - %status%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflows",
+            "fields": [
+              {
+                "field": "GAUGE"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "status",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Stuck workflows",
+        "description": "Ongoing workflow runs that need a person, by class and reason (paused_error, stalled, paused_manual, overdue).",
+        "line_label": "%workflow_class% - %reason%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflows_stuck",
+            "fields": [
+              {
+                "field": "GAUGE"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "reason",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Late workflow waits",
+        "description": "Deadlines an on_timeout: :notify wait missed, by class and step: the run keeps waiting for its signal.",
+        "line_label": "%workflow_class% - %step%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflow_wait_overdue_total",
+            "fields": [
+              {
+                "field": "COUNTER"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "step",
+                "value": "*"
+              }
+            ]
+          }
+        ]
       }
     ]
   }

data/lib/pgbus/integrations/appsignal/subscriber.rb

@@ -76,7 +76,8 @@ module Pgbus
               subscribe("pgbus.outbox.publish") { |event| on_outbox_publish(event) },
               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.consumer.recycle") { |event| on_consumer_recycle(event) },
+              *Pgbus::Metrics::WorkflowMetrics::EVENTS.map { |name| subscribe(name) { |event| on_workflow(event) } }
               # pgbus.client.pool is deliberately NOT subscribed here — the
               # minutely Probe#track_pool already reports pgbus_pool_size /
               # pgbus_pool_available gauges for AppSignal (see probe.rb).
@@ -273,6 +274,20 @@ module Pgbus
               { reason: payload[:reason], kind: "consumer" }
             )
           end
+
+          # ── Workflows (issue #540) ──────────────────────────────────────
+
+          # The same names and labels as Metrics::Subscriber
+          # (Pgbus::Metrics::WorkflowMetrics), as AppSignal custom metrics.
+          def on_workflow(event)
+            Pgbus::Metrics::WorkflowMetrics.samples(event.name, event.payload).each do |kind, name, value, tags|
+              case kind
+              when :histogram then ::Appsignal.add_distribution_value(name, value, tags)
+              when :counter then ::Appsignal.increment_counter(name, value, tags)
+              when :gauge then ::Appsignal.set_gauge(name, value, tags)
+              end
+            end
+          end
         end
       end
     end

data/lib/pgbus/mcp/rack_app.rb

@@ -19,7 +19,8 @@ module Pgbus
     #
     # Security: requests are rejected with 401 unless they carry the configured
     # token (or pass the supplied auth callable). Run it on an internal network
-    # / behind your VPN, never internet-exposed.
+    # / behind your VPN, never internet-exposed. With config.mcp_write_tools on
+    # it also serves the workflow write tools (issue #550): gate it.
     #
     # DNS-rebinding protection: since mcp 0.23 the transport validates the Host
     # header (loopback only, by default) and the Origin header (same-origin
@@ -123,9 +124,13 @@ module Pgbus
         @token.nil? && @auth.nil?
       end
 
+      # With config.mcp_write_tools on, an unauthenticated mount can change
+      # workflow runs. Warned, not refused: a mount inside the app's own
+      # authenticated routes is gated where this class cannot see it.
       def warn_unauthenticated!
         Pgbus.logger.warn do
-          "[Pgbus::MCP] HTTP diagnostic server mounted without authentication. " \
+          writes = Server.write_tools? ? " config.mcp_write_tools is on: anyone who reaches it can change workflow runs." : ""
+          "[Pgbus::MCP] HTTP diagnostic server mounted without authentication.#{writes} " \
             "Pass token: or auth: to Pgbus::MCP.rack_app, and keep it on an internal network."
         end
       end

data/lib/pgbus/mcp/runner.rb

@@ -66,7 +66,8 @@ module Pgbus
 
       def log_start(allow_payloads)
         mode = allow_payloads ? "payloads ALLOWED" : "payloads redacted"
-        Pgbus.logger.info { "[Pgbus::MCP] starting read-only diagnostic server over stdio (#{mode})" }
+        kind = Server.write_tools? ? "diagnostic server with the workflow write tools ON (mcp_write_tools)" : "read-only diagnostic server"
+        Pgbus.logger.info { "[Pgbus::MCP] starting #{kind} over stdio (#{mode})" }
       end
     end
   end

data/lib/pgbus/mcp/serialization.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "active_support/core_ext/time"
+
+module Pgbus
+  module MCP
+    # How MCP tools write a data-source row as JSON: times as ISO 8601 UTC,
+    # symbols as strings, keys as strings, recursively.
+    module Serialization
+      module_function
+
+      def serialize(value)
+        case value
+        when Hash then value.to_h { |key, nested| [key.to_s, serialize(nested)] }
+        when Array then value.map { |nested| serialize(nested) }
+        when Symbol then value.to_s
+        when Time, DateTime, ActiveSupport::TimeWithZone then value.utc.iso8601
+        else value
+        end
+      end
+    end
+  end
+end