pgbus 0.20.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2c853eab253c7e6bbf570e0cd92ada59c071752fb3d6d8a0a5f796790aedfa3
-  data.tar.gz: 8922bdb2140718d03a2bf1cf3600c714fc2b181c566f1213091f83b28385b74c
+  metadata.gz: 1c3c6921f17cfc002f7177240a3d1b2c202a78c7127e8f0da75a75ebcaf365d1
+  data.tar.gz: b73396771876a230b1b62b6b30dceb87329be7259810c5346fd4a3fc78f59991
 SHA512:
-  metadata.gz: d9d38d6bb97efc078db1afa031b51cfe2512aac285d664d09e23ce8a4a3b1a3eda075134a8b7e8d234834c31c543a6095c3cdb3bbef77cec3f3f53744e7019eb
-  data.tar.gz: 0e15d3375c20815ea3f0fbc34381e824c308f7210b67189fae56a1f11abeb3381d9b71b2b418e46c4d24bf5f5b80df3360adfccf5c7b77a02a6533d963b30699
+  metadata.gz: 5667ec2a6ebd1ef9e09f5f89818e69784267b3aa0c13a0b5cef2782b346af2361c106454fbb58d67a688b48f451483327fa4f3edc0a1d9a82664aa599af52454
+  data.tar.gz: 83d7a44001fe09db593caacc788307198361279c023b7ed2ed8397fdec17fb353fa44087d9a973857951835d6cb1206314ade872a99d85586988561be2477a85

data/CHANGELOG.md

@@ -1,15 +1,68 @@
 ## [Unreleased]
 
+## [0.21.0] - 2026-10-19
+
+### Added
+
+- **feat(workflow): `wait_timeout:` takes a per-run deadline — a method name or a lambda, returning a duration or a Time (issue #574).** `step :await_reply, wait_for: :replied, wait_timeout: -> { subject.expires_at }, on_timeout: :run` (or `wait_timeout: :reply_deadline`, an instance method) is evaluated once per attempt, when the step parks, on the workflow instance (`instance_exec`, as `skip_if:` is, with `subject` and `arguments`). It returns a `Time` (or anything with `#to_time` that is not a String): the deadline itself, so `timeout_at` no longer drifts by the time the run took to reach the wait (the steps before it, queue latency, a reattempt); a deadline already past is `timeout_at = now`, and the next sweep applies `on_timeout`. Or a Duration or a number of seconds, counted from park and required to be positive. Or `nil`: no timeout for this attempt. Anything else raises `ArgumentError` at the gate, which, like an error the callable raises, goes through the step's exception policies (the default pauses the run), so the run is never left parked silently. The callable runs under the run's row lock in a savepoint, so a query of its own that fails in the database (a dropped column, a `statement_timeout`) is handled the same way instead of aborting the run's transaction. `on_timeout:` still needs `wait_timeout:`, and a callable counts as given (its default is `:pause!`). Under `on_timeout: :notify` the callable is evaluated again at each notice: a `Time` after now is the next deadline, a duration moves the deadline one period on as a static `wait_timeout:` does, and `nil` or a `Time` not after now (the same `expires_at`) clears `timeout_at`, so the wait is reported once and keeps waiting with no deadline instead of re-firing on a past time (the Workflows list and the run's page still say since when it is late, and that no further late notice is due); one that raises or returns anything else at a notice pauses the run with that error (the sweep holds the run's row lock, under which no `on_exception` block may run). A pause still moves the deadline by its length, as for a static one. `StepDefinition#wait_timeout` stays the static seconds (nil for a callable); `#wait_timeout_callable` and `#dynamic_wait_timeout?` read the per-run one. The definitions page (`/pgbus/workflows/definitions/:workflow_class`) shows each signal step's wait timeout, `dynamic (per run)` for a callable, and `pgbus_workflow_stats` sends it per step as `wait_timeout` (seconds or `"dynamic"`). A static `wait_timeout:` (seconds or a Duration) is unchanged, validated when the class loads and counted from park. Refs #574.
+- **feat(workflow): `woken?` and `signal_ready?` — a `wait_for:` step's guards can tell a signalled step from one that has not waited yet (issue #572).** Guards run before the signal gate, on every claim of the step, so a `skip_if:` on the state the signal reports (skip a wait the record already passed) recorded a step `signal!` woke as `skipped` and never ran its body, and a signal sent before the step's first claim stayed `pending` for good because the gate never ran. Two step readers, usable in `skip_if:`, `cancel_if` and the body, answer it without claiming anything (the gate still claims, after the guards): `signal_ready?` is true when the gate runs this attempt with a signal, the one the step holds or a pending one its `wait_for:` matcher takes; `woken?` is true when this attempt holds a signal before its gate (`signal!` woke it, or an earlier attempt took one and reattempted or failed into a pause), false on a first claim even with a buffered signal. Both keep one answer for the whole attempt, are false after an `on_timeout: :run` wake and in a step without `wait_for:`, and raise `Pgbus::Workflow::NotInStep` outside a step. The recipe: `step :await_shipped, wait_for: :shipped, skip_if: -> { subject.shipped? && !signal_ready? } do … end` skips a run that started after the order shipped and completes a woken step or one whose signal came first, consuming the signal. `skip_if` still runs on every claim, and no step outcome changes for an existing class. A guard that skips takes no signal: a pending one stays pending for a later `wait_for:` step, as with an outside `skip!`. Refs #572.
+- **feat(workflow): `start!` takes `actor:` and `reason:` for the audit trail (issue #571).** `Pgbus::Workflow.start!(subject = nil, idempotency_key: nil, actor: nil, reason: nil, **arguments)`: the run's `started` event records the actor and the reason, and its first `step_scheduled` event the actor, as `rerun!` and every outside verb already did, so a run started by a person says who started it and why (`ReportWorkflow.start!(actor: "alice", reason: "monthly close")`). Without them the trail says `"app"` with no reason, as before; the default is `actor || "app"`, the outside verbs' convention, so `actor: ""` is kept as given. Neither is stored in the run's `arguments` or changes the run row. A duplicate start (same `idempotency_key`, `duplicate_start?` true) still writes no events, so the first caller's actor stays on the trail. Refs #571.
+
+### Changed
+
+- **`actor:` and `reason:` are reserved keywords of `Pgbus::Workflow.start!` (issue #571).** Like `idempotency_key:`, they are taken for the audit trail and no longer reach the run's `arguments`. A workflow that receives an argument literally named `actor` or `reason` through `start!` renames it, e.g. `start!(subject, requested_by: "alice")` read as `arguments[:requested_by]`. Runs already started keep their stored arguments, and `rerun!` copies them as stored. Refs #571.
+
+### Fixed
+
+- **The workflows one-ongoing index predicate dumps the same `schema.rb` line from a migrated and from a schema-loaded database (issue #573).** `pgbus:add_workflows` and the fresh-install migration declared `idx_pgbus_workflows_one_ongoing` with `where: "status IN ('ready','performing','waiting','paused')"`. `status` is a `varchar`, so Postgres stored the list as `varchar` literals cast to `text[]`; `db:schema:load` parses that dumped string into a different expression, and each later dump flipped the line depending on which kind of database it came from. Both templates now write `status::text IN (…)`, whose stored form replays to itself. The index means the same either way, so existing installs need nothing. An app that wants a stable dump can recreate the index in a migration of its own: `remove_index :pgbus_workflows, name: "idx_pgbus_workflows_one_ongoing"`, then `add_index :pgbus_workflows, [:workflow_class, :subject_type, :subject_id], unique: true, where: "status::text IN ('ready','performing','waiting','paused')", name: "idx_pgbus_workflows_one_ongoing"` (both run in the migration's transaction, so the constraint never lapses; `remove_index` takes an ACCESS EXCLUSIVE lock, so `pgbus_workflows` is locked against reads and writes (workers, workflow starts and the dashboard wait) until the migration commits), and dump the schema again. Refs #573.
+- **A guard that ends a `wait_for:` step after a reattempt consumes the signal the step holds (issue #572).** A woken attempt that called `reattempt!` (or failed into a pause and was resumed) kept its signal `claimed` for the next attempt, whose row carries no `signal_id` until its gate runs. When `cancel_if` or `skip_if` ended that next attempt (or a guard raised and its `on_exception` policy skipped or cancelled, or a deploy had declared the step a `removed_step` meanwhile), the signal stayed `claimed` forever. The attempt now records the held signal before its outcome, so it is consumed when the step ends and kept when it reattempts or pauses, as for any attempt. Refs #572.
+
+## [0.20.1] - 2026-10-18
+
 ### Added
 
 - **feat(workflow): `on_timeout: :notify` — a soft wait deadline that reports a late signal and keeps waiting.** A fifth `on_timeout:` value for a `wait_for:` step with `wait_timeout:`. When the sweep (or `expire_wait`) finds the wait past `timeout_at`, it records the `wait_timed_out` event and instruments `pgbus.workflow.wait_timed_out` with `action: "notify"`, as the other values do, and then leaves the run and the step as they are: same attempt, still `waiting`, no step outcome, no StepJob. Only `timeout_at` moves, to the next deadline on the `wait_timeout:` grid (one `wait_timeout:` on; a sweep that missed several deadlines reports them once and moves to the first one ahead of now), so a late signal still wakes that attempt and its body runs with `received_signal` set and `timed_out?` false. A paused run's wait still does not fire while paused. Replaces the `on_timeout: :run` + `reattempt!` workaround, whose `reattempted` outcomes counted as failures in `pgbus_workflow_steps_total`. New counter `pgbus_workflow_wait_overdue_total{workflow_class, step}` (Prometheus, StatsD, AppSignal), one per late notice (a sweep that missed several deadlines sends one). The dashboard says "Waiting for signal `approved` since 3h ago (late since 2h ago). The next late notice goes out in 1h" once a deadline passed (and "A late notice goes out …" before), and the timeline marks every `wait_timed_out` with a dashed line, listed as text below the chart; the workflow rows (and so the `pgbus_workflows` / `pgbus_workflow` MCP tools) gain `on_timeout` and `late_since` (the first missed deadline). The bundled AppSignal dashboard gets a "Late workflow waits" graph. Refs #565.
+
+### Fixed
+
+- **An `:until_executed` job keeps its uniqueness key while its retry waits (issue #564).** A job that rescheduled itself with `retry_job(wait:)` (or `retry_on … wait:`) enqueued the retry through the key it held (#333), but the key row kept pointing at the running attempt, and the executor deleted the row by key when that attempt archived. For the whole wait nothing held the key: a fresh `perform_later` with the same key ran beside the retry, and the retry's own success then deleted the newcomer's row. Now the row is handed to the retry the way a first enqueue takes one: before the retry is sent or parked it is unbound onto the retry's queue and re-stamped (`UniquenessKey.unbind!`), and once sent it is bound to the retry (`UniquenessKey.bind!(…, acquired_at:)`). A retry parked behind its `limits_concurrency` slot (with `to: 1, on_conflict: :block` the attempt holds that slot, so its retry always parks) keeps the unbound row until it runs; a retry dropped by its limit, or whose send failed before any message existed, hands the row back to the attempt. A finishing message (success, dead-letter, or a failed `:while_executing` attempt) releases only the row it holds (`UniquenessKey.release_held_by!`): the row bound to it, or an unbound row acquired no later than the message was sent, so a retry that finishes before its bind still releases it; a row handed to a retry, or that a successor took after an operator released it, stays. The dashboard's discards (a job, a failed job, a dead-lettered copy, an event, the bulk discards and queue purges) release the same way, through `UniquenessKey.release_all_held_by!` for the bulk ones, judged by when the job's message was sent: a failed job's queued message gives its own `enqueued_at`, and the dead-letter header gains `source_msg_id` and `source_enqueued_at` so a DLQ copy names its original and when it was sent. Without a send time only a lock bound to the message is freed (the reaper takes the rest). The Locks page's Release still deletes by key. A retry enqueued outside the executor, or by a job running inline inside another job, moves nothing; one enqueued by an attempt that no longer holds the key moves nothing and logs a warning. The dispatcher's reaper now counts a key carried by a job parked in `pgbus_blocked_executions` (legacy double-encoded rows included) as live: a parked `:until_executed` job's unbound row was reaped once it was older than twice the visibility timeout. A parked job's `created_at` now comes from the database clock, like its lock's, so discarding it from the dashboard frees its lock even when the app's clock runs behind the database's. A job's lock now records its queue the way the queue's table spells it (`Uniqueness.lock_queue_name`: `orders-handler` → `orders_handler`), at every place a job lock is written or released (adapter, executor, recurring scheduler), so a release that knows only the table (the dashboard) or a worker that spells the queue the table's way still finds it; a multi-queue worker also hands the executor the configured queue name instead of one cut from the table name. For such a queue, a job in flight during the upgrade holds its lock under the old spelling: its first retry after the upgrade does not take the lock (logged), so it and that job's later retries run without one until the job finishes, and the stale lock is reclaimed by the reaper once its message is gone. `config.queue_prefix` is now stored the way the queue tables spell it (`"my-app"` reads back as `"my_app"`): table names are unchanged, and every place that strips the prefix off a table name (the dashboard, the worker, the lock queue above) strips it whole. A prefix with a leading, trailing or doubled underscore (`"myapp_"`) is kept as written and now warned about at boot: `queue_name` collapses the separator after it only for a queue name that needs normalizing (`myapp__orders`, but `myapp_orders_handler` for `orders-handler`), so the reaper cannot resolve such a queue's lock back to its table: a lock orphaned there (a worker crash before its release) is never reclaimed and has to be released by key. A job's own release and the dashboard still match. `Pgbus::ActiveJob::Delivery.current` gains `enqueued_at` and `job_id`. Refs #564.
+- **Presence statements run under the ActiveRecord adapter's lock (issue #566).** `Pgbus::Streams::Presence` ran every statement on `connection.raw_connection`, and `raw_connection` holds the adapter's lock only long enough to hand the `PG::Connection` out. On a pinned pool, as in transactional tests, every thread shares one adapter and that lock is all that serialises them, so the streamer's seat sweep (`expire_seats!` on the dispatcher thread) could be in flight on the same libpq connection a request thread was about to use. Every presence statement (`join`, `leave`, `touch`, `set_state`, `members`, `count`, `sweep!`, `expire_seats!` and the seat-schema probe) now goes through `Presence.exec_params`, which holds `adapter.lock` for the whole statement. The adapter lock is reentrant, so a request already inside a transaction re-enters it; unpinned, it is a `NullLock` and nothing changes. The seat-schema probe also no longer runs while holding the probe's own mutex: a sweep that probed under it while a pinned request inside `ActiveRecord::Base.transaction` (which holds the adapter's lock for its whole block) asked `seats?` deadlocked both threads. Two threads may now probe at once: a true answer one of them stored is never taken back, and a probe that a `reset_schema_cache!` overtook stores nothing. `Presence.connection` still returns the raw `PG::Connection`.
+
+## [0.20.0] - 2026-10-18
+
+### Added
+
 - **feat(mcp): workflow write tools, opt-in — resume, cancel, skip step, resume at, run now, signal (issue #550).** `config.mcp_write_tools = true` (default `false`, validated as a boolean, read when `Pgbus::MCP::Server.build` runs) adds `pgbus_workflow_resume`, `pgbus_workflow_cancel`, `pgbus_workflow_skip_step`, `pgbus_workflow_resume_at` (`step`), `pgbus_workflow_run_now` and `pgbus_workflow_signal` (`name`, a JSON object `payload` capped at `workflow_max_payload_size`, an optional `idempotency_key`; name and key at most 255 characters) to the MCP server; off, they are never constructed and `tools/list` does not show them, and the read tools are the same either way. Each takes `workflow_id`, a required `reason` (1–500 characters after trimming) and an optional `expected_status` (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); a verb the run's `available_actions` does not allow answers `ok: false` with the allowed list; otherwise the call goes through the dashboard's `Web::DataSource` action, is recorded on the run's audit trail with its reason as actor `mcp` (`mcp:<client name>` when the transport knows the client; the name is stripped of control characters and capped at 100), and answers `{ ok:, reason:, workflow: }` with the `pgbus_workflow` detail as the run is after the call (refusals included), payloads always redacted, plus `available_actions` for a disallowed verb and `code`/`status` when the guarded transition refused it; an unexpected failure answers a fixed reason rather than the exception's text (the DataSource logged it). The tools live on their own base class, `Pgbus::MCP::WriteTool` (not `BaseTool`), annotated `readOnlyHint: false, destructiveHint: true` (`idempotentHint: true` on cancel only: a retried skip or resume at can act again once the run parked or paused again). No bulk tools: `pgbus_workflows_attention` groups the stuck runs and `pgbus_workflows` lists a group's runs, one call per run. The server's instructions name them when they are on, `pgbus mcp` logs it at start, and an unauthenticated `Pgbus::MCP.rack_app` with them on warns that anyone who reaches it can change workflow runs. `Workflow#signal!`, `Workflow.signal!` (by subject), `Signals.deliver` and `DataSource#signal_workflow` take an optional `reason:`, recorded on the `signal_received` event. Refs #550.
 - **feat(dashboard): workflow insights — per-class pipeline, step performance, funnel, per-revision numbers, MCP stats (issue #549).** `/pgbus/workflows/definitions` (linked from the Workflows page as "Insights by class") has one row per workflow class — every registered `Pgbus::Workflow` subclass and every class name still in `pgbus_workflows` — with its ongoing, paused and stuck runs, the runs that finished or were cancelled in the window and their p50/p95 end-to-end duration, a "definition not loaded" badge for a class that no longer loads and a count of ongoing runs on removed steps. `/pgbus/workflows/definitions/:workflow_class` (`OrderWorkflow` or `Billing::OrderWorkflow`) shows the class's steps in order as a pipeline: each step with the runs sitting at it now (scheduled, running, waiting, paused), the p50/p95/p99 run time and pickup latency (scheduled → started) of its attempts that finished in the window and their failure (an error was recorded), reattempt and skip rates, with a "few samples" note under 20 attempts; then runs started, finished and cancelled per bucket and the end-to-end duration distribution (ApexCharts, each with a caption and a data table), a funnel (of the runs started in the window, how many reached each step and where each one is now) and the same numbers for the last five app revisions, newest first, marking a step whose failure rate rose more than five points over the revision before. Window 1 h, 24 h (default), 7 d or 30 d, capped at `workflow_retention`. Every count of runs a list filter can express links to the Workflows list filtered to exactly those runs (percentiles, rates, the funnel's "reached" and the per-revision rows are text), which gains `ended_from`/`ended_to` filters (when a run finished or was cancelled; also on `pgbus_workflows`); need-attention counts open `/pgbus/workflows/attention?workflow_class=…`, the attention groups narrowed to the class (also `pgbus_workflows_attention(workflow_class:)`), and each removed step a run still sits on links to those runs. Throughput buckets follow the dashboard zone's wall clock: a day bucket starts at local midnight on both sides of a DST change (at its first hour where a DST change skips midnight). Runs and attempts dated after now are not counted. Read from the step and run rows on the existing indexes (`Web::WorkflowInsightsQueries`, one query per block): on ~1 M step rows over 20 classes a class's page reads in 26 ms and the list in 86 ms over 24 h (median; budgets 250 / 500 ms, `rake bench:workflow_insights`), about 300 ms over 30 d (reported, no budget); `WorkflowEntry.stuck_reason_counts` takes `workflow_class:` so a class's page counts only its own stuck runs. A class name from the URL that no class or run has is never constantized. `Web::DataSource` gains `workflow_definitions(window:)` and `workflow_definition(workflow_class, window:)`; the MCP server gains the read-only `pgbus_workflow_definitions` and `pgbus_workflow_stats`. The workflows guide gains a Monitoring section with example Prometheus alerts. Refs #549.
 - **feat(dashboard): the Workflows pages — list and filters, needs attention, step timeline, audit trail, operator actions, MCP read tools (issue #542).** `/pgbus/workflows` lists every run newest first (ongoing by default, each state, or all) with its class, subject, status badge, current step, start and last activity, and says in words what it is doing and what happens next ("Waiting for batch `OrderWorkflow#notify_vendors` (7 of 12 jobs done)", "Paused on `capture`: Timeout::Error — resume or cancel", "Overdue: `welcome` was due 2h ago; the sweep sends it again"); filters on class, current step, error class, subject type and id, workflow id and a created-at range combine and survive paging. `/pgbus/workflows/:workflow_id` shows the arguments, an ApexCharts range-bar timeline (one row per attempt split into waited, queued and ran, coloured by outcome, with waits and pauses as their own segments, zoomable), every attempt with the same durations as text, its worker, app revision, error, backtrace and cause chain, the signals, the audit trail ("Resumed by dashboard:alice: SMTP fixed"), whether it started on an older definition, rerun links both ways, and the actions `available_actions` allows: Resume (labelled "retry `capture`" or "continue with `receipt`"), Resume at a chosen step, Run now, Skip step, Send signal (a JSON object, sent once per form render), Rerun and Cancel, each with a confirm and an optional reason, each reporting the real outcome ("Not done: the run is cancelled now."). `/pgbus/workflows/attention` groups every stuck run by class, step, reason and error class with a count, first/last seen and the newest message, with bulk Resume/Cancel (500 runs per press, each through its own guarded transition: "Resumed 212; 2 had already moved on"). The home page gains a Workflows card ("N ongoing (M paused) · K need attention") and the nav a Workflows link. New settings: `config.web_actor` (`->(request) { name }`, recorded as `"dashboard:<name>"`, or `"dashboard"`) and `config.workflow_subject_url` (`->(subject_type, subject_id) { url }`, linked only when it is an http(s) URL or a same-site path). `Web::DataSource` gains `workflows`, `workflows_count`, `workflow_detail`, `workflow_attention_groups`, the home counts and the actions; `Pgbus::WorkflowEntry.attention_groups` / `attention_ids` share the stuck-reason `CASE` with the gauge. The MCP server gains the read-only `pgbus_workflows`, `pgbus_workflow` and `pgbus_workflows_attention`, with arguments, outputs, signal payloads and error text behind `include_payloads`. Refs #542.
 - **feat(workflows): waiting steps — `fan_out` over a batch, signals, wait timeouts (issue #541).** `fan_out :notify_vendors do |b| b.add(*jobs) end` runs its body with a recording builder, then opens one batch (`Pgbus.batch`, described `Class#step workflow_id`) whose `on_complete` is `Pgbus::Workflow::BatchFinishedJob`; the step and the run park as `waiting` and the callback resumes the run once every member finished: the step completes and the next is scheduled, or, with a dead-lettered member, `on_batch_failure:` (`:pause!` default, `:cancel!`, `:skip!`) applies with `Pgbus::Workflow::FanOutFailed` ("1 of 3 jobs dead-lettered") recorded. A verb or an exception in the body ends the step before any batch exists, the body cannot set the batch's callbacks, an empty batch resolves at once, and a reattempt or `resume!` re-runs the whole body on a fresh batch (members must be idempotent). `step :capture, wait_for: :payment_confirmed` parks the step at its gate until `wf.signal!(:payment_confirmed, payload: {…}, idempotency_key: event.id, actor:)` arrives, or `OrderWorkflow.signal!(order, :payment_confirmed, …, missing: :raise | :ignore)` by subject; signals live in `pgbus_workflow_signals` (`Pgbus::WorkflowSignal`, `pending → claimed → consumed`), early ones are buffered, a redelivery with the same key stores nothing and answers `duplicate_delivery?`, `wait_for:` takes a name, a `Pgbus::Workflow::SignalMatcher.new(:shipped) { |payload| … }` or any `matches?(signal)` object, the body reads `received_signal.payload` with indifferent access, and a claimed signal survives a `reattempt!` or a failure that pauses. The wake is a step-row write, so its StepJob goes out only after the signal commits; a paused run takes the signal but stays paused until `resume!`, and `resume!` of a run paused while waiting puts it back to `waiting`. `wait_timeout: 2.days, on_timeout: :pause! | :cancel! | :skip! | :run` bounds a wait (`timeout:` still bounds the run): the dispatcher's sweep applies it under the row lock (`Pgbus::Workflow::WaitTimedOut` for `:pause!`; `:run` runs the body with `timed_out?` true), a late signal stays pending, and the time a run spends paused does not count against the wait. The sweep also resolves a fan_out step whose batch finished but whose callback was lost, and pauses one whose batch row is gone (outcome unknown, whatever `on_batch_failure:` says). `skip!` outside a step skips the step a waiting run waits on. New runner verbs `park`, `wake`, `resolve`, `rewait` and outside verbs `skip`, `signal` in `States`; events `step_waiting`, `signal_received`, `signal_claimed`, `wait_timed_out`, `fan_out_opened`, `fan_out_finished`; instrumentation `pgbus.workflow.signal` and `pgbus.workflow.wait_timed_out`; stuck reason `waiting_overdue` past the new `workflow_waiting_visibility_threshold` (7 days). `TestHelpers` gains `deliver_signal`, `complete_fan_out` and `expire_wait`, and `speedrun_workflow` raises `Pgbus::Workflow::StepWaiting` naming what the step waits for. Schema: `pgbus:add_workflows` and `pgbus:install` carry the five step columns and the signals table; installs that ran the core migration add them with `rails generate pgbus:add_workflow_signals [--database=pgbus]` (`pgbus:update` detects it), and `start!` raises `WaitingStepsUnmigrated` (or `BatchCallbacksUnmigrated` for a `fan_out` before `pgbus:add_batch_callback_jobs`) until then. Refs #541.
 - **feat(workflows): `Pgbus::Workflow`, durable multi-step workflows.** A workflow class declares steps (`step :name, wait:, skip_if:, timeout:, job_options:, on_exception:`, anonymous `step { … }`, `step :method`, `step def …`, `before_step:`/`after_step:`), `cancel_if`, class-level `on_exception` policies and `set_step_job_options`; `SignupWorkflow.start!(user, plan: "pro")` writes the run and its first step row in one transaction, and each step attempt is a `pgbus_workflow_steps` row and one `Pgbus::Workflow::StepJob`, sent only by the step row's after-commit callback (so `start!` inside an app transaction on the same database sends nothing until it commits). Inside a step, `subject` (GlobalID, nil once the record is gone), `arguments` (ActiveJob::Arguments, indifferent access, capped at `workflow_max_payload_size`) and the verbs `pause!`, `cancel!`, `reattempt!(wait:)`, `skip!`, `finished!`; outside, `resume!`, `resume_at!(:step)`, `pause!`, `cancel!`, `run_now!`, `reschedule!(at:)` and `rerun!`, each with `actor:`/`reason:`, all checked against one transition table, `Pgbus::Workflow::States` (`available_actions`). An unhandled exception never re-raises into ActiveJob: the step row records the class, message, cleaned and capped backtrace, cause chain, `hostname:pid` and app revision, `Pgbus::ErrorReporter` gets it with the workflow, step and attempt as context, and the run pauses unless a policy (`action:`, `matching:`, `wait:`, `max_reattempts:`, `terminal_action:`, `report:`, or an imperative block) says otherwise. Idempotent by contract: `output(**values)` is written in the UPDATE that completes the step and `output_of(:step)` reads the latest completed attempt only; `step_idempotency_key` is the same on every attempt (`attempt_idempotency_key` differs); `start!(…, idempotency_key:)` returns the existing run with `duplicate_start?`. At most one ongoing run per `(class, subject)` (`Pgbus::Workflow::AlreadyRunning`); subject-less runs are not limited. `removed_step :name` gravestones skip a step a live run still names; an unknown step pauses with `StepNotDefined`; `definition_digest` marks runs that started on an older definition. Every transition writes a `pgbus_workflow_events` row (actor, reason, details) in its own transaction (`wf.events`). Housekeeping from the dispatcher: a redelivered StepJob whose row is still in progress means its worker died, and `workflow_stall_action` (`:pause`, `:reattempt`, `:cancel`) applies at once; the sweep (`workflow_sweep_interval`) stalls a step past its `timeout:` or `workflow_stall_threshold`, re-sends lost scheduled steps and emits `pgbus.workflow.gauge`; finished/cancelled runs are deleted after `workflow_retention` (30 days). Instrumented as `pgbus.workflow.step`, `pgbus.workflow_finished`, `pgbus.workflow_paused`, `pgbus.workflow_cancelled`, `pgbus.workflow.stall_detected`; Prometheus/StatsD and AppSignal get `pgbus_workflow_step_duration_seconds`, `pgbus_workflow_steps_total`, run counters and the `pgbus_workflows`/`pgbus_workflows_stuck` gauges (the AppSignal dashboard gains a workflows row; the StatsD backend sends any `*_seconds` histogram as a `*_ms` timer, × 1000). Instrumentation and error reports of a transition made inside an app's transaction go out when that transaction commits, never on its rollback. `Pgbus::Workflow::TestHelpers` (`perform_next_step`, `run_step_inline`, `speedrun_workflow`) runs steps inline; `Pgbus::Workflow::StepContext` and Pgbus's log context tag a running step; `Pgbus::ActiveJob::Delivery.current` exposes the running job's `msg_id`/`read_ct`. Set up with `rails generate pgbus:add_workflows` (`pgbus:update` detects the missing tables; fresh `pgbus:install` includes them). New configuration: `workflow_queue`, `workflow_retention`, `workflow_sweep_interval`, `workflow_stall_threshold`, `workflow_stall_action`, `workflow_max_payload_size`, `workflow_error_backtrace_lines`. Refs #540.
+
+### Fixed
+
+- **A blank signal `idempotency_key` is no key (issue #550).** `wf.signal!(…, idempotency_key: "")` (or whitespace) stored `""` as a real key, so every later signal sent with a blank key dedup'd against the first: it answered `duplicate_delivery?` and was never stored, leaving a step waiting for it. `Signals.deliver` now treats a blank key as none, for app code, the dashboard and the MCP tool alike. Refs #550.
+
+## [0.19.4] - 2026-10-17
+
+### Fixed
+
+- **`Pgbus.batch` inside a database transaction counts the jobs that enqueue after commit, and waits for them.** A job with Active Job's `enqueue_after_transaction_commit` added inside an open transaction is enqueued only when the transaction commits, after the block has returned and its thread tag is gone. The batch counted nothing, finished empty when the block returned and sent its `on_complete` (and `on_success`) callback before any member job existed; the jobs then ran outside the batch. Even a rolled-back transaction sent the callback. Now `b.add`, `batch.add` and `perform_later` record the batch on the job instance (`enqueue_batch_id`, transient: never serialized, cleared once the enqueue is done), the adapter tags and counts each job from it at the real enqueue, and the batch starts processing (or an open batch re-checks for finish) through `ActiveRecord.after_all_transactions_commit`, after every deferred enqueue has counted itself in. On a rollback nothing is sent, no callback fires and the batch row is rolled back with the transaction. A deferred first attempt discarded at enqueue (uniqueness or concurrency `on_conflict: :discard`) is uncounted as before, and a `retry_on` re-enqueue still re-joins without a second count. Outside a transaction nothing changes, including the queries a batch runs. Known gaps: a bare `ActiveJob.perform_all_later` inside the block does not record the batch (use `b.add`); a `batch.add` inside a transaction raises `AlreadyFinished` when the transaction commits, not at the `add` line, if the batch finished in the meantime; a batch row on a separate `connects_to` database is not part of the caller's transaction. Refs #553.
+- **AppSignal: the job's transaction is current while the job runs, and carries its error (issue #552).** The AppSignal subscriber opened the `background_job` transaction from a finish-only notification callback, after the job had run, and completed it in the same call. `pgbus.job_failed` fired after that, so its `Appsignal.set_error` found no current transaction and reported nothing: a job whose class no longer exists (`ActiveJob::UnknownJobClassError`) or whose arguments cannot be deserialized retried and dead-lettered with nothing in AppSignal but the counters, an error raised inside `perform` arrived only as an action-less sample from the Rails error reporter, and job code calling `Appsignal.add_tags`, `set_error` or `instrument` attached to nothing. Event handlers had the same shape. The subscriber now listens to `pgbus.executor.execute` and `pgbus.event_processed` on both sides (`start` and `finish`): the `<JobClass>#perform` / `<Handler>#handle` transaction opens before the job or handler runs, is current for the whole execution (deserialize, perform, archive), records the exception the execution raised and completes at the end, so an error raised inside `perform` lands on it once, with its duration and queue start. A failure raised before that span opens (a message body that is not JSON, an event that cannot be built, a dead-letter move that failed) is reported from `pgbus.job_failed` / `pgbus.event_failed` on a transaction of its own with the same action and tags; an error the span already recorded is not reported twice. A transaction that is already current is reused and left to its owner to complete, as AppSignal's own ActiveJob hook does, and a span inside another of its kind restores the outer one when it finishes. Like that hook, the span records any exception that ends the execution, so a job interrupted between `perform` and the archive (an `Async::Stop` on shutdown under `execution_mode: :async`, an `Interrupt`) now shows up as an error sample too. The counters and the `pgbus_job_duration_ms` / `pgbus_event_duration_ms` distributions are recorded as before, once per execution. Refs #552.
+
+## [0.19.3] - 2026-10-17
+
+### Added
+
 - **`Pgbus.stream_key` works inside a non-main Ractor.** `Pgbus.stream_key`, `Pgbus.stream_key!` and `Pgbus.stream_name_budget` (and `Streams::Key`) check the queue-name budget against the `queue_prefix`, which they read from `Pgbus.configuration`; a non-main Ractor cannot read that (it holds the logger and the app's callables), so they raised `Ractor::IsolationError` there. Each `Pgbus.finalize!` and finalizing `Pgbus.configure` (so also the engine's `after_initialize` and `pgbus start`) now publishes `Pgbus.configuration_snapshot`, a Ractor-shareable `Pgbus::Configuration::Snapshot` of the settings a non-main Ractor reads (the `queue_prefix` for now), and the stream keys read it there. On the main Ractor nothing changes: they read the live configuration, so a `queue_prefix` set through a setter still applies at once; a non-main Ractor sees it from the next finalize. Refs #527.
-- **Deploy tasks: one-time work owed by a release, run once the fleet has rolled over.** Declare a backfill, data fix or cache warm in `config/deploy_tasks.yml` (the shape of `recurring.yml` minus `schedule:`, plus `version:` and `every_deploy:`) or `config.deploy_tasks`; the scheduler enqueues it once per `(key, version)` (or once per revision for an `every_deploy:` task) after every live pgbus process reports the new app revision and a worker on it is alive, so it never runs on old code during the overlap window and two schedulers never both fire it. It is not exactly-once: a failure between the enqueue and recording the run can repeat a task after a scheduler restart, and a scheduler killed between claiming and enqueueing loses that arm, so deploy tasks must be idempotent. Every pgbus process stamps the revision (`config.app_revision`, `PGBUS_REVISION`, `DASH_VERSION`, `KAMAL_VERSION` or the `REVISION` file) into its heartbeat. The dashboard gets a "Deploy tasks" page with the rollover status, Run now and Enable/Disable; run history lives in `pgbus_deploy_task_runs` (`deploy_task_run_retention`, default 90 days); `pgbus.deploy_task.enqueue` is instrumented and the MCP server gains `pgbus_deploy_tasks`. Set up with `rails generate pgbus:add_deploy_tasks` (`pgbus:update` detects the missing tables). Refs #536.
+
+### Fixed
+
+- **The dashboard's confirm and alert dialogs open centred again (issue #529).** The engine's stylesheet is built with Tailwind 4, whose preflight sets `margin: 0` on every element. A modal `<dialog>` keeps the browser's `inset: 0` but lost the `margin: auto` that centres it inside that inset, so every Pause, Purge and Delete confirmation opened in the top-left corner. Both dialogs now carry `m-auto`. The confirm dialog's Confirm button was white on yellow (1.91:1). It now uses the dark-on-yellow warning colours (`bg-yellow-400 text-yellow-950`), and the axe gate audits an open confirm dialog in light and dark mode. Refs #529.
+
+## [0.19.2] - 2026-10-17
+
+### Added
+
 - **`pgbus.event_dead_lettered`: the event consumer says when it dead-letters an event.** A job that exhausted `max_retries` emitted `pgbus.job_dead_lettered`; an event moved to `<queue>_dlq` the same way emitted nothing, so a pager, an error tracker or a metrics counter had no push signal for dead events. `Process::Consumer` now emits `pgbus.event_dead_lettered` once per dead-lettered event, after `move_to_dead_letter` returns and the failed-event row is cleared, with `queue_name` (logical), `routing_key`, `handler` (the class that owns the queue in this process, or nil), `event_id`, `read_ct`, `msg_id` and `error` (the class of the last recorded failure, or nil). `handler` is nil unless exactly one subscriber owns the queue. A body that is not a JSON object (unparseable text, or a jsonb scalar or array written straight to the queue) is still dead-lettered, with `routing_key`, `handler` and `event_id` nil, and its `error` is the consumer's own failure to read it (`JSON::ParserError`, `NoMethodError` or `TypeError`): no handler ran. A move that raises emits nothing. A subscriber that raises is logged at debug level and does not change the outcome: the message stays dead-lettered, with one `dead_lettered` stat, no `failed` stat and no circuit-breaker failure. The AppSignal and metrics subscribers count it as `pgbus_event_count` with `status: "dead_lettered"`, tagged `handler` and `routing_key`. `pgbus.job_dead_lettered` and the consumer's success path are unchanged: the envelope is parsed a second time only on the dead-letter branch. Refs #543.
 - **feat(batches): `Pgbus.batch do |b| … end`, a builder for starting a batch.** `b.on_complete`, `b.on_success` and `b.on_failure` take an ActiveJob class or a configured instance; `b.add(*jobs)` takes job instances (each keeps its own `.set(wait:, queue:, priority:)`) and sends them in one bulk enqueue. The batch row exists, and a `uniqueness_key` is held, before the block runs, and the batch stays pending until the block returns, so the calls can come in any order and a job that finishes while the block is still adding cannot finish the batch early. Every `perform_later` inside the block joins the batch, as inside `Batch#enqueue`. With `on_conflict: :discard` or `:log` and the key held, the block does not run. Inside a job, `batch(description: …) { |b| … }` opens a new, independent batch; `batch` without a block still reads the job's own batch. A member job adds siblings with `batch.add(NextJob.new(id))`, the open-batch form of `batch.enqueue { … }`. `Pgbus::Batch.start` is the same as `Pgbus.batch`, and `Pgbus::Batch.new` + `#enqueue` stay as the lower-level API. Refs #538.
 
@@ -17,14 +70,11 @@
 
 - **The batch completion callback is `on_complete`.** `Pgbus::Batch.new(on_complete:)`, the builder's `b.on_complete` and the `#on_complete` reader replace `on_finish`, which keeps working as a deprecated alias until 1.0 and logs one warning per process. The database columns stay `on_finish_class` / `on_finish_job` until the 1.0 schema cleanup, so batches created before upgrading still fire, and the `pgbus.batch_finished` instrumentation event keeps its name. The dashboard's batch page labels the callback "On Complete". Refs #538.
 
-### Fixed
+## [0.19.1] - 2026-10-17
 
-- **An `:until_executed` job keeps its uniqueness key while its retry waits (issue #564).** A job that rescheduled itself with `retry_job(wait:)` (or `retry_on … wait:`) enqueued the retry through the key it held (#333), but the key row kept pointing at the running attempt, and the executor deleted the row by key when that attempt archived. For the whole wait nothing held the key: a fresh `perform_later` with the same key ran beside the retry, and the retry's own success then deleted the newcomer's row. Now the row is handed to the retry the way a first enqueue takes one: before the retry is sent or parked it is unbound onto the retry's queue and re-stamped (`UniquenessKey.unbind!`), and once sent it is bound to the retry (`UniquenessKey.bind!(…, acquired_at:)`). A retry parked behind its `limits_concurrency` slot (with `to: 1, on_conflict: :block` the attempt holds that slot, so its retry always parks) keeps the unbound row until it runs; a retry dropped by its limit, or whose send failed before any message existed, hands the row back to the attempt. A finishing message (success, dead-letter, or a failed `:while_executing` attempt) releases only the row it holds (`UniquenessKey.release_held_by!`): the row bound to it, or an unbound row acquired no later than the message was sent, so a retry that finishes before its bind still releases it; a row handed to a retry, or that a successor took after an operator released it, stays. The dashboard's discards (a job, a failed job, a dead-lettered copy, an event, the bulk discards and queue purges) release the same way, through `UniquenessKey.release_all_held_by!` for the bulk ones, judged by when the job's message was sent: a failed job's queued message gives its own `enqueued_at`, and the dead-letter header gains `source_msg_id` and `source_enqueued_at` so a DLQ copy names its original and when it was sent. Without a send time only a lock bound to the message is freed (the reaper takes the rest). The Locks page's Release still deletes by key. A retry enqueued outside the executor, or by a job running inline inside another job, moves nothing; one enqueued by an attempt that no longer holds the key moves nothing and logs a warning. The dispatcher's reaper now counts a key carried by a job parked in `pgbus_blocked_executions` (legacy double-encoded rows included) as live: a parked `:until_executed` job's unbound row was reaped once it was older than twice the visibility timeout. A parked job's `created_at` now comes from the database clock, like its lock's, so discarding it from the dashboard frees its lock even when the app's clock runs behind the database's. A job's lock now records its queue the way the queue's table spells it (`Uniqueness.lock_queue_name`: `orders-handler` → `orders_handler`), at every place a job lock is written or released (adapter, executor, recurring scheduler), so a release that knows only the table (the dashboard) or a worker that spells the queue the table's way still finds it; a multi-queue worker also hands the executor the configured queue name instead of one cut from the table name. For such a queue, a job in flight during the upgrade holds its lock under the old spelling: its first retry after the upgrade does not take the lock (logged), so it and that job's later retries run without one until the job finishes, and the stale lock is reclaimed by the reaper once its message is gone. `config.queue_prefix` is now stored the way the queue tables spell it (`"my-app"` reads back as `"my_app"`): table names are unchanged, and every place that strips the prefix off a table name (the dashboard, the worker, the lock queue above) strips it whole. A prefix with a leading, trailing or doubled underscore (`"myapp_"`) is kept as written and now warned about at boot: `queue_name` collapses the separator after it only for a queue name that needs normalizing (`myapp__orders`, but `myapp_orders_handler` for `orders-handler`), so the reaper cannot resolve such a queue's lock back to its table: a lock orphaned there (a worker crash before its release) is never reclaimed and has to be released by key. A job's own release and the dashboard still match. `Pgbus::ActiveJob::Delivery.current` gains `enqueued_at` and `job_id`. Refs #564.
-- **Presence statements run under the ActiveRecord adapter's lock (issue #566).** `Pgbus::Streams::Presence` ran every statement on `connection.raw_connection`, and `raw_connection` holds the adapter's lock only long enough to hand the `PG::Connection` out. On a pinned pool, as in transactional tests, every thread shares one adapter and that lock is all that serialises them, so the streamer's seat sweep (`expire_seats!` on the dispatcher thread) could be in flight on the same libpq connection a request thread was about to use. Every presence statement (`join`, `leave`, `touch`, `set_state`, `members`, `count`, `sweep!`, `expire_seats!` and the seat-schema probe) now goes through `Presence.exec_params`, which holds `adapter.lock` for the whole statement. The adapter lock is reentrant, so a request already inside a transaction re-enters it; unpinned, it is a `NullLock` and nothing changes. The seat-schema probe also no longer runs while holding the probe's own mutex: a sweep that probed under it while a pinned request inside `ActiveRecord::Base.transaction` (which holds the adapter's lock for its whole block) asked `seats?` deadlocked both threads. Two threads may now probe at once: a true answer one of them stored is never taken back, and a probe that a `reset_schema_cache!` overtook stores nothing. `Presence.connection` still returns the raw `PG::Connection`.
-- **A blank signal `idempotency_key` is no key (issue #550).** `wf.signal!(…, idempotency_key: "")` (or whitespace) stored `""` as a real key, so every later signal sent with a blank key dedup'd against the first: it answered `duplicate_delivery?` and was never stored, leaving a step waiting for it. `Signals.deliver` now treats a blank key as none, for app code, the dashboard and the MCP tool alike. Refs #550.
-- **`Pgbus.batch` inside a database transaction counts the jobs that enqueue after commit, and waits for them.** A job with Active Job's `enqueue_after_transaction_commit` added inside an open transaction is enqueued only when the transaction commits, after the block has returned and its thread tag is gone. The batch counted nothing, finished empty when the block returned and sent its `on_complete` (and `on_success`) callback before any member job existed; the jobs then ran outside the batch. Even a rolled-back transaction sent the callback. Now `b.add`, `batch.add` and `perform_later` record the batch on the job instance (`enqueue_batch_id`, transient: never serialized, cleared once the enqueue is done), the adapter tags and counts each job from it at the real enqueue, and the batch starts processing (or an open batch re-checks for finish) through `ActiveRecord.after_all_transactions_commit`, after every deferred enqueue has counted itself in. On a rollback nothing is sent, no callback fires and the batch row is rolled back with the transaction. A deferred first attempt discarded at enqueue (uniqueness or concurrency `on_conflict: :discard`) is uncounted as before, and a `retry_on` re-enqueue still re-joins without a second count. Outside a transaction nothing changes, including the queries a batch runs. Known gaps: a bare `ActiveJob.perform_all_later` inside the block does not record the batch (use `b.add`); a `batch.add` inside a transaction raises `AlreadyFinished` when the transaction commits, not at the `add` line, if the batch finished in the meantime; a batch row on a separate `connects_to` database is not part of the caller's transaction. Refs #553.
-- **AppSignal: the job's transaction is current while the job runs, and carries its error (issue #552).** The AppSignal subscriber opened the `background_job` transaction from a finish-only notification callback, after the job had run, and completed it in the same call. `pgbus.job_failed` fired after that, so its `Appsignal.set_error` found no current transaction and reported nothing: a job whose class no longer exists (`ActiveJob::UnknownJobClassError`) or whose arguments cannot be deserialized retried and dead-lettered with nothing in AppSignal but the counters, an error raised inside `perform` arrived only as an action-less sample from the Rails error reporter, and job code calling `Appsignal.add_tags`, `set_error` or `instrument` attached to nothing. Event handlers had the same shape. The subscriber now listens to `pgbus.executor.execute` and `pgbus.event_processed` on both sides (`start` and `finish`): the `<JobClass>#perform` / `<Handler>#handle` transaction opens before the job or handler runs, is current for the whole execution (deserialize, perform, archive), records the exception the execution raised and completes at the end, so an error raised inside `perform` lands on it once, with its duration and queue start. A failure raised before that span opens (a message body that is not JSON, an event that cannot be built, a dead-letter move that failed) is reported from `pgbus.job_failed` / `pgbus.event_failed` on a transaction of its own with the same action and tags; an error the span already recorded is not reported twice. A transaction that is already current is reused and left to its owner to complete, as AppSignal's own ActiveJob hook does, and a span inside another of its kind restores the outer one when it finishes. Like that hook, the span records any exception that ends the execution, so a job interrupted between `perform` and the archive (an `Async::Stop` on shutdown under `execution_mode: :async`, an `Interrupt`) now shows up as an error sample too. The counters and the `pgbus_job_duration_ms` / `pgbus_event_duration_ms` distributions are recorded as before, once per execution. Refs #552.
-- **The dashboard's confirm and alert dialogs open centred again (issue #529).** The engine's stylesheet is built with Tailwind 4, whose preflight sets `margin: 0` on every element. A modal `<dialog>` keeps the browser's `inset: 0` but lost the `margin: auto` that centres it inside that inset, so every Pause, Purge and Delete confirmation opened in the top-left corner. Both dialogs now carry `m-auto`. The confirm dialog's Confirm button was white on yellow (1.91:1). It now uses the dark-on-yellow warning colours (`bg-yellow-400 text-yellow-950`), and the axe gate audits an open confirm dialog in light and dark mode. Refs #529.
+### Added
+
+- **Deploy tasks: one-time work owed by a release, run once the fleet has rolled over.** Declare a backfill, data fix or cache warm in `config/deploy_tasks.yml` (the shape of `recurring.yml` minus `schedule:`, plus `version:` and `every_deploy:`) or `config.deploy_tasks`; the scheduler enqueues it once per `(key, version)` (or once per revision for an `every_deploy:` task) after every live pgbus process reports the new app revision and a worker on it is alive, so it never runs on old code during the overlap window and two schedulers never both fire it. It is not exactly-once: a failure between the enqueue and recording the run can repeat a task after a scheduler restart, and a scheduler killed between claiming and enqueueing loses that arm, so deploy tasks must be idempotent. Every pgbus process stamps the revision (`config.app_revision`, `PGBUS_REVISION`, `DASH_VERSION`, `KAMAL_VERSION` or the `REVISION` file) into its heartbeat. The dashboard gets a "Deploy tasks" page with the rollover status, Run now and Enable/Disable; run history lives in `pgbus_deploy_task_runs` (`deploy_task_run_retention`, default 90 days); `pgbus.deploy_task.enqueue` is instrumented and the MCP server gains `pgbus_deploy_tasks`. Set up with `rails generate pgbus:add_deploy_tasks` (`pgbus:update` detects the missing tables). Refs #536.
 
 ## [0.19.0] - 2026-10-16
 

data/README.md

@@ -887,7 +887,7 @@ wf.events.map(&:event)                              # ["started", "step_schedule
 - **Idempotent by contract**: `output(charge_id: …)` is durable once the step completes and later steps read it with `output_of(:charge)`; `step_idempotency_key` is the same on every attempt, for the external API; `start!(order, idempotency_key: "checkout-#{order.id}")` returns the existing run.
 - **One ongoing run per subject** and class: a second `start!` raises `Pgbus::Workflow::AlreadyRunning`. Subject-less runs are not limited.
 - **Fan-out**: `fan_out :notify_vendors do |b| b.add(*jobs) end` opens one batch for the jobs and parks the step until every member finished; the batch's `on_complete` resumes the run, and a dead-lettered member applies `on_batch_failure:` (`:pause!` by default) with `Pgbus::Workflow::FanOutFailed` recorded. A reattempt, or `resume!` of a failed fan-out step, re-runs the whole body on a fresh batch, so members must be idempotent; a run resumed while its batch is still running keeps waiting on that batch.
-- **Signals**: `step :capture, wait_for: :payment_confirmed do … received_signal.payload["amount"] … end` parks until `wf.signal!(:payment_confirmed, payload: {…}, idempotency_key: event.id)`, or by subject, `OrderWorkflow.signal!(order, :payment_confirmed, …, missing: :ignore)`. Early signals are buffered, a redelivery with the same key is a no-op (`duplicate_delivery?`), and matchers (`Pgbus::Workflow::SignalMatcher.new(:shipped) { |payload| … }`) narrow what a step takes. `wait_timeout: 2.days, on_timeout: :pause!` (or `:cancel!`, `:skip!`, `:run`) puts a deadline on the wait, fired by the dispatcher's sweep; `on_timeout: :notify` makes it a soft deadline that reports the late signal (a `wait_timed_out` event and `pgbus_workflow_wait_overdue_total`) and keeps waiting for it, its deadline moving one `wait_timeout:` on each time (a sweep that missed several reports them once).
+- **Signals**: `step :capture, wait_for: :payment_confirmed do … received_signal.payload["amount"] … end` parks until `wf.signal!(:payment_confirmed, payload: {…}, idempotency_key: event.id)`, or by subject, `OrderWorkflow.signal!(order, :payment_confirmed, …, missing: :ignore)`. Early signals are buffered, a redelivery with the same key is a no-op (`duplicate_delivery?`), and matchers (`Pgbus::Workflow::SignalMatcher.new(:shipped) { |payload| … }`) narrow what a step takes. `wait_timeout: 2.days, on_timeout: :pause!` (or `:cancel!`, `:skip!`, `:run`) puts a deadline on the wait, fired by the dispatcher's sweep; `on_timeout: :notify` makes it a soft deadline that reports the late signal (a `wait_timed_out` event and `pgbus_workflow_wait_overdue_total`) and keeps waiting for it, its deadline moving one `wait_timeout:` on each time (a sweep that missed several reports them once). `wait_timeout:` also takes a method name or a lambda, evaluated on the run when the step parks: `wait_timeout: -> { subject.expires_at }` returns a `Time` (or any non-String value with `#to_time`, such as a DateTime or a TimeWithZone: the deadline itself, however long the run took to reach the wait), a positive Duration or number of seconds counted from park, or `nil` for no timeout.
 - **Housekeeping**: a worker that dies mid-step is noticed when its message comes back (the visibility heartbeat keeps a live one invisible); a hung step stalls after its `timeout:` or `workflow_stall_threshold`; the dispatcher re-sends lost steps and deletes finished runs after `workflow_retention` (30 days).
 - **Metrics** for Prometheus/StatsD and AppSignal: per-step duration histograms and counters, and gauges of runs by status and by stuck reason.
 - **Dashboard**: `/pgbus/workflows` lists runs with what each one does next, filters by state, class, step, error, subject, id and creation date, and shows a run's timeline, attempts, signals and audit trail with its actions (Resume, Resume at, Run now, Skip step, Send signal, Rerun, Cancel); `/pgbus/workflows/attention` groups the stuck runs for bulk Resume/Cancel. `config.web_actor = ->(request) { … }` names the operator on the audit trail and `config.workflow_subject_url = ->(type, id) { … }` links the subject. The MCP server reads the same through `pgbus_workflows`, `pgbus_workflow` and `pgbus_workflows_attention`, and with `config.mcp_write_tools = true` acts on one run per call through `pgbus_workflow_resume`, `_cancel`, `_skip_step`, `_resume_at`, `_run_now` and `_signal` ([write tools](#write-tools-opt-in)).

data/app/helpers/pgbus/workflow_insights_helper.rb

@@ -72,6 +72,14 @@ module Pgbus
 
     def pgbus_insight_definition_path(name, window) = pgbus.workflow_definition_path(name, window: window.name)
 
+    # A signal step's wait timeout: its length, or "dynamic (per run)" for a
+    # wait_timeout: lambda or method name (issue #574).
+    def pgbus_insight_wait_timeout(seconds)
+      return t("pgbus.workflow_insights.show.pipeline.wait_timeout_dynamic") if seconds == "dynamic"
+
+      pgbus_duration(seconds)
+    end
+
     def pgbus_insight_kind(step)
       key = step[:declared] ? step[:kind] : "undeclared"
       return unless KIND_TONES.key?(key)

data/app/models/pgbus/workflow_entry.rb

@@ -55,8 +55,9 @@ module Pgbus
     #   paused_manual paused otherwise (the step called pause!, or an outside pause!)
     #   overdue       ready, its scheduled step due more than +threshold+ ago
     #   waiting_overdue waiting longer than +waiting_threshold+ on a step
-    #                 without a wait_timeout: (only with +waiting_threshold+,
-    #                 which needs the waiting-step columns)
+    #                 without a deadline (no timeout_at: no wait_timeout:, or
+    #                 a per-run one that set none or cleared it; only with
+    #                 +waiting_threshold+, which needs the waiting-step columns)
     # With +workflow_class+, that class's runs only (the workflow insights,
     # issue #549).
     def self.stuck_reason_counts(threshold:, now: Time.current, waiting_threshold: nil, workflow_class: nil)

data/app/views/pgbus/workflows/definitions/_step_card.html.erb

@@ -10,6 +10,9 @@
     </h3>
     <%= pgbus_insight_kind(step) %>
   </div>
+  <% if step[:wait_timeout] %>
+    <p class="mt-2 text-sm"><span class="text-gray-600 dark:text-gray-300"><%= t("pgbus.workflow_insights.show.pipeline.wait_timeout") %></span> <span class="font-mono text-gray-900 dark:text-white"><%= pgbus_insight_wait_timeout(step[:wait_timeout]) %></span></p>
+  <% end %>
   <ul class="mt-3 grid grid-cols-2 gap-x-3 gap-y-1 text-sm" aria-label="<%= t("pgbus.workflow_insights.show.pipeline.now_label") %>">
     <% Pgbus::WorkflowInsightsHelper::LIVE_STATUSES.each do |status| %>
       <% count = step[:counts][status.to_sym] %>

data/config/locales/da.yml

@@ -1167,6 +1167,8 @@ da:
           skipped: Sprunget over
           step_link: Igangværende kørsler ved %{step}
           title: Pipeline
+          wait_timeout: Ventetidsgrænse
+          wait_timeout_dynamic: dynamisk (pr. kørsel)
           window_label: Forsøg der sluttede i vinduet
         summary:
           attention: Kræver handling
@@ -1350,6 +1352,7 @@ da:
         waiting_batch_html: Venter på batch %{batch} (%{done} af %{total} jobs færdige).
         waiting_signal_html: Venter på signalet %{signal} siden %{ago}.
         waiting_signal_late_html: Venter på signalet %{signal} siden %{ago} (forsinket siden %{late}). Næste forsinkelsesbesked sendes %{time}.
+        waiting_signal_late_no_deadline_html: Venter på signalet %{signal} siden %{ago} (forsinket siden %{late}). Der sendes ikke flere forsinkelsesbeskeder.
         waiting_signal_notify_html: Venter på signalet %{signal} siden %{ago}. En forsinkelsesbesked sendes %{time}, og ventetiden fortsætter.
         waiting_signal_timeout_html: Venter på signalet %{signal} siden %{ago}. Ventetiden udløber %{time}.
         waiting_step_html: Venter på %{step}.

data/config/locales/de.yml

@@ -1167,6 +1167,8 @@ de:
           skipped: Übersprungen
           step_link: Laufende Läufe bei %{step}
           title: Pipeline
+          wait_timeout: Warte-Timeout
+          wait_timeout_dynamic: dynamisch (pro Lauf)
           window_label: Im Zeitfenster beendete Versuche
         summary:
           attention: Brauchen Aufmerksamkeit
@@ -1350,6 +1352,7 @@ de:
         waiting_batch_html: Wartet auf Stapel %{batch} (%{done} von %{total} Jobs erledigt).
         waiting_signal_html: Wartet auf Signal %{signal} seit %{ago}.
         waiting_signal_late_html: Wartet auf Signal %{signal} seit %{ago} (verspätet seit %{late}). Die nächste Verspätungsmeldung folgt %{time}.
+        waiting_signal_late_no_deadline_html: Wartet auf Signal %{signal} seit %{ago} (verspätet seit %{late}). Es folgt keine weitere Verspätungsmeldung.
         waiting_signal_notify_html: Wartet auf Signal %{signal} seit %{ago}. Eine Verspätungsmeldung folgt %{time}, und das Warten geht weiter.
         waiting_signal_timeout_html: Wartet auf Signal %{signal} seit %{ago}. Das Warten läuft ab %{time}.
         waiting_step_html: Wartet auf %{step}.

data/config/locales/en.yml

@@ -1167,6 +1167,8 @@ en:
           skipped: Skipped
           step_link: Ongoing runs at %{step}
           title: Pipeline
+          wait_timeout: Wait timeout
+          wait_timeout_dynamic: dynamic (per run)
           window_label: Attempts that finished in the window
         summary:
           attention: Need attention
@@ -1350,6 +1352,7 @@ en:
         waiting_batch_html: Waiting for batch %{batch} (%{done} of %{total} jobs done).
         waiting_signal_html: Waiting for signal %{signal} since %{ago}.
         waiting_signal_late_html: Waiting for signal %{signal} since %{ago} (late since %{late}). The next late notice goes out %{time}.
+        waiting_signal_late_no_deadline_html: Waiting for signal %{signal} since %{ago} (late since %{late}). No further late notice is due.
         waiting_signal_notify_html: Waiting for signal %{signal} since %{ago}. A late notice goes out %{time}, and the wait goes on.
         waiting_signal_timeout_html: Waiting for signal %{signal} since %{ago}. The wait times out %{time}.
         waiting_step_html: Waiting on %{step}.

data/config/locales/es.yml

@@ -1167,6 +1167,8 @@ es:
           skipped: Omitidos
           step_link: Ejecuciones en curso en %{step}
           title: Pipeline
+          wait_timeout: Tiempo de espera
+          wait_timeout_dynamic: dinámico (por ejecución)
           window_label: Intentos terminados en la ventana
         summary:
           attention: Requieren atención
@@ -1350,6 +1352,7 @@ es:
         waiting_batch_html: Esperando el lote %{batch} (%{done} de %{total} trabajos terminados).
         waiting_signal_html: Esperando la señal %{signal} desde %{ago}.
         waiting_signal_late_html: Esperando la señal %{signal} desde %{ago} (con retraso desde %{late}). El próximo aviso de retraso sale %{time}.
+        waiting_signal_late_no_deadline_html: Esperando la señal %{signal} desde %{ago} (con retraso desde %{late}). No sale ningún otro aviso de retraso.
         waiting_signal_notify_html: Esperando la señal %{signal} desde %{ago}. Un aviso de retraso sale %{time} y la espera continúa.
         waiting_signal_timeout_html: Esperando la señal %{signal} desde %{ago}. La espera caduca %{time}.
         waiting_step_html: Esperando a %{step}.

data/config/locales/fi.yml

@@ -1167,6 +1167,8 @@ fi:
           skipped: Ohitettu
           step_link: Käynnissä olevat ajot vaiheessa %{step}
           title: Putki
+          wait_timeout: Odotuksen aikaraja
+          wait_timeout_dynamic: dynaaminen (ajokohtainen)
           window_label: Ikkunassa päättyneet yritykset
         summary:
           attention: Vaatii toimia
@@ -1350,6 +1352,7 @@ fi:
         waiting_batch_html: Odottaa erää %{batch} (%{done} / %{total} tehtävää valmis).
         waiting_signal_html: Odottaa signaalia %{signal}, alkoi %{ago}.
         waiting_signal_late_html: Odottaa signaalia %{signal}, alkoi %{ago} (myöhässä alkaen %{late}). Seuraava myöhästymisilmoitus lähtee %{time}.
+        waiting_signal_late_no_deadline_html: Odottaa signaalia %{signal}, alkoi %{ago} (myöhässä alkaen %{late}). Uusia myöhästymisilmoituksia ei lähde.
         waiting_signal_notify_html: Odottaa signaalia %{signal}, alkoi %{ago}. Myöhästymisilmoitus lähtee %{time}, ja odotus jatkuu.
         waiting_signal_timeout_html: Odottaa signaalia %{signal}, alkoi %{ago}. Odotus aikakatkaistaan %{time}.
         waiting_step_html: Odottaa vaihetta %{step}.

data/config/locales/fr.yml

@@ -1167,6 +1167,8 @@ fr:
           skipped: Ignorées
           step_link: Exécutions en cours à %{step}
           title: Pipeline
+          wait_timeout: Délai d'attente
+          wait_timeout_dynamic: dynamique (par exécution)
           window_label: Tentatives terminées dans la fenêtre
         summary:
           attention: À traiter
@@ -1350,6 +1352,7 @@ fr:
         waiting_batch_html: En attente du lot %{batch} (%{done} travaux sur %{total} terminés).
         waiting_signal_html: En attente du signal %{signal} depuis %{ago}.
         waiting_signal_late_html: En attente du signal %{signal} depuis %{ago} (en retard depuis %{late}). Le prochain avis de retard part %{time}.
+        waiting_signal_late_no_deadline_html: En attente du signal %{signal} depuis %{ago} (en retard depuis %{late}). Aucun autre avis de retard ne part.
         waiting_signal_notify_html: En attente du signal %{signal} depuis %{ago}. Un avis de retard part %{time} et l'attente continue.
         waiting_signal_timeout_html: En attente du signal %{signal} depuis %{ago}. L'attente expire %{time}.
         waiting_step_html: En attente de %{step}.

data/config/locales/it.yml

@@ -1167,6 +1167,8 @@ it:
           skipped: Saltati
           step_link: Esecuzioni in corso a %{step}
           title: Pipeline
+          wait_timeout: Timeout di attesa
+          wait_timeout_dynamic: dinamico (per esecuzione)
           window_label: Tentativi terminati nella finestra
         summary:
           attention: Richiedono attenzione
@@ -1350,6 +1352,7 @@ it:
         waiting_batch_html: In attesa del lotto %{batch} (%{done} lavori su %{total} completati).
         waiting_signal_html: In attesa del segnale %{signal} da %{ago}.
         waiting_signal_late_html: In attesa del segnale %{signal} da %{ago} (in ritardo da %{late}). Il prossimo avviso di ritardo parte %{time}.
+        waiting_signal_late_no_deadline_html: In attesa del segnale %{signal} da %{ago} (in ritardo da %{late}). Non parte nessun altro avviso di ritardo.
         waiting_signal_notify_html: In attesa del segnale %{signal} da %{ago}. Un avviso di ritardo parte %{time} e l'attesa continua.
         waiting_signal_timeout_html: In attesa del segnale %{signal} da %{ago}. L'attesa scade %{time}.
         waiting_step_html: In attesa di %{step}.

data/config/locales/ja.yml

@@ -1167,6 +1167,8 @@ ja:
           skipped: スキップ
           step_link: "%{step} の進行中の実行"
           title: パイプライン
+          wait_timeout: 待機タイムアウト
+          wait_timeout_dynamic: 動的（実行ごと）
           window_label: 期間内に終了した試行
         summary:
           attention: 要対応
@@ -1350,6 +1352,7 @@ ja:
         waiting_batch_html: バッチ %{batch} を待機中です（%{total} 件中 %{done} 件のジョブが完了）。
         waiting_signal_html: シグナル %{signal} を %{ago} から待機中です。
         waiting_signal_late_html: シグナル %{signal} を %{ago} から待機中です（%{late} から遅延）。次の遅延通知は %{time} に送られます。
+        waiting_signal_late_no_deadline_html: シグナル %{signal} を %{ago} から待機中です（%{late} から遅延）。これ以上の遅延通知は送られません。
         waiting_signal_notify_html: シグナル %{signal} を %{ago} から待機中です。遅延通知は %{time} に送られ、待機は続きます。
         waiting_signal_timeout_html: シグナル %{signal} を %{ago} から待機中です。待機は %{time} にタイムアウトします。
         waiting_step_html: "%{step} を待機中です。"

data/config/locales/nb.yml

@@ -1167,6 +1167,8 @@ nb:
           skipped: Hoppet over
           step_link: Pågående kjøringer ved %{step}
           title: Pipeline
+          wait_timeout: Tidsgrense for venting
+          wait_timeout_dynamic: dynamisk (per kjøring)
           window_label: Forsøk som ble avsluttet i vinduet
         summary:
           attention: Trenger tiltak
@@ -1350,6 +1352,7 @@ nb:
         waiting_batch_html: Venter på gruppen %{batch} (%{done} av %{total} jobber ferdige).
         waiting_signal_html: Venter på signalet %{signal} siden %{ago}.
         waiting_signal_late_html: Venter på signalet %{signal} siden %{ago} (forsinket siden %{late}). Neste forsinkelsesvarsel sendes %{time}.
+        waiting_signal_late_no_deadline_html: Venter på signalet %{signal} siden %{ago} (forsinket siden %{late}). Det sendes ingen flere forsinkelsesvarsler.
         waiting_signal_notify_html: Venter på signalet %{signal} siden %{ago}. Et forsinkelsesvarsel sendes %{time}, og ventingen fortsetter.
         waiting_signal_timeout_html: Venter på signalet %{signal} siden %{ago}. Ventetiden utløper %{time}.
         waiting_step_html: Venter på %{step}.

data/config/locales/nl.yml

@@ -1167,6 +1167,8 @@ nl:
           skipped: Overgeslagen
           step_link: Lopende runs bij %{step}
           title: Pipeline
+          wait_timeout: Wachttime-out
+          wait_timeout_dynamic: dynamisch (per run)
           window_label: Pogingen die in het venster eindigden
         summary:
           attention: Aandacht nodig
@@ -1350,6 +1352,7 @@ nl:
         waiting_batch_html: Wacht op groep %{batch} (%{done} van %{total} taken klaar).
         waiting_signal_html: Wacht op signaal %{signal}, gestart %{ago}.
         waiting_signal_late_html: Wacht op signaal %{signal}, gestart %{ago} (te laat sinds %{late}). De volgende melding over de vertraging gaat %{time} uit.
+        waiting_signal_late_no_deadline_html: Wacht op signaal %{signal}, gestart %{ago} (te laat sinds %{late}). Er gaat geen nieuwe melding over de vertraging meer uit.
         waiting_signal_notify_html: Wacht op signaal %{signal}, gestart %{ago}. Een melding over de vertraging gaat %{time} uit, en het wachten gaat door.
         waiting_signal_timeout_html: Wacht op signaal %{signal}, gestart %{ago}. De wachttijd verloopt %{time}.
         waiting_step_html: Wacht op %{step}.

data/config/locales/pt.yml

@@ -1167,6 +1167,8 @@ pt:
           skipped: Ignoradas
           step_link: Execuções em curso em %{step}
           title: Pipeline
+          wait_timeout: Tempo limite de espera
+          wait_timeout_dynamic: dinâmico (por execução)
           window_label: Tentativas terminadas na janela
         summary:
           attention: Precisam de atenção
@@ -1350,6 +1352,7 @@ pt:
         waiting_batch_html: Aguardando o lote %{batch} (%{done} de %{total} trabalhos concluídos).
         waiting_signal_html: Aguardando o sinal %{signal} desde %{ago}.
         waiting_signal_late_html: Aguardando o sinal %{signal} desde %{ago} (atrasado desde %{late}). O próximo aviso de atraso sai %{time}.
+        waiting_signal_late_no_deadline_html: Aguardando o sinal %{signal} desde %{ago} (atrasado desde %{late}). Não sai mais nenhum aviso de atraso.
         waiting_signal_notify_html: Aguardando o sinal %{signal} desde %{ago}. Um aviso de atraso sai %{time} e a espera continua.
         waiting_signal_timeout_html: Aguardando o sinal %{signal} desde %{ago}. A espera expira %{time}.
         waiting_step_html: Aguardando %{step}.

data/config/locales/sv.yml

@@ -1167,6 +1167,8 @@ sv:
           skipped: Överhoppade
           step_link: Pågående körningar vid %{step}
           title: Pipeline
+          wait_timeout: Väntetidsgräns
+          wait_timeout_dynamic: dynamisk (per körning)
           window_label: Försök som avslutades i fönstret
         summary:
           attention: Behöver åtgärd
@@ -1350,6 +1352,7 @@ sv:
         waiting_batch_html: Väntar på gruppen %{batch} (%{done} av %{total} jobb klara).
         waiting_signal_html: Väntar på signalen %{signal} sedan %{ago}.
         waiting_signal_late_html: Väntar på signalen %{signal} sedan %{ago} (sen sedan %{late}). Nästa förseningsavisering går ut %{time}.
+        waiting_signal_late_no_deadline_html: Väntar på signalen %{signal} sedan %{ago} (sen sedan %{late}). Ingen fler förseningsavisering går ut.
         waiting_signal_notify_html: Väntar på signalen %{signal} sedan %{ago}. En förseningsavisering går ut %{time}, och väntan fortsätter.
         waiting_signal_timeout_html: Väntar på signalen %{signal} sedan %{ago}. Väntan tar slut %{time}.
         waiting_step_html: Väntar på %{step}.

data/lib/generators/pgbus/templates/add_workflows.rb.erb

@@ -32,8 +32,10 @@ class AddPgbusWorkflows < ActiveRecord::Migration<%= migration_version %>
 
     add_index :pgbus_workflows, :workflow_id,
       unique: true, name: "idx_pgbus_workflows_workflow_id", if_not_exists: true
+    # status::text keeps the predicate stable in schema.rb: without the cast, a
+    # migrated and a schema-loaded database dump it differently (issue #573).
     add_index :pgbus_workflows, [:workflow_class, :subject_type, :subject_id],
-      unique: true, where: "status IN ('ready','performing','waiting','paused')",
+      unique: true, where: "status::text IN ('ready','performing','waiting','paused')",
       name: "idx_pgbus_workflows_one_ongoing", if_not_exists: true
     add_index :pgbus_workflows, [:workflow_class, :idempotency_key],
       unique: true, where: "idempotency_key IS NOT NULL",

data/lib/generators/pgbus/templates/migration.rb.erb

@@ -238,8 +238,10 @@ class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
 
     add_index :pgbus_workflows, :workflow_id,
       unique: true, name: "idx_pgbus_workflows_workflow_id"
+    # status::text keeps the predicate stable in schema.rb: without the cast, a
+    # migrated and a schema-loaded database dump it differently (issue #573).
     add_index :pgbus_workflows, [:workflow_class, :subject_type, :subject_id],
-      unique: true, where: "status IN ('ready','performing','waiting','paused')",
+      unique: true, where: "status::text IN ('ready','performing','waiting','paused')",
       name: "idx_pgbus_workflows_one_ongoing"
     add_index :pgbus_workflows, [:workflow_class, :idempotency_key],
       unique: true, where: "idempotency_key IS NOT NULL",

data/lib/pgbus/configuration/workflow_settings.rb

@@ -12,7 +12,7 @@ module Pgbus
     #   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)
+    #                                                   # deadline 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

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

@@ -11,7 +11,7 @@ module Pgbus
         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).
+          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): wait_timeout (a wait_for: step's wait_timeout: in seconds, "dynamic" when a lambda or a method name sets it per run, null without one), 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(

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

@@ -9,7 +9,7 @@ module Pgbus
         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.
+          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 deadline: no wait_timeout, or a per-run one that set none or cleared it after a :notify notice). 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(

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/data_source/workflow_list.rb

@@ -158,12 +158,14 @@ module Pgbus
           end
         end
 
-        # { step_id => the first deadline its wait missed } for waiting steps
-        # with a deadline, one query: the first wait_timed_out event of each.
+        # { step_id => the first deadline its wait missed } for steps waiting
+        # on a signal, one query: the first wait_timed_out event of each.
         # Only on_timeout: :notify leaves a step waiting after that event
-        # (issue #565): every other on_timeout ends the attempt.
+        # (issue #565): every other on_timeout ends the attempt. A per-run
+        # wait_timeout: may have cleared the deadline at that notice (issue
+        # #574), so a step without one is looked up too.
         def late_since(waiting)
-          steps = waiting.select { |step| step_attribute(step, :timeout_at) }
+          steps = waiting.select { |step| step_attribute(step, :wait_for) }
           return {} if steps.empty?
 
           WorkflowEvent.where(workflow_id: steps.map(&:workflow_id), step_id: steps.map(&:id),

data/lib/pgbus/web/workflow_insights_report.rb

@@ -47,14 +47,14 @@ module Pgbus
         )
       end
 
-      # [{ name:, kind:, removed:, declared: }] in pipeline order.
+      # [{ name:, kind:, removed:, declared:, wait_timeout: }] in pipeline order.
       def step_list(klass, stats, ongoing, reached, stopped)
         seen = (stats.keys + ongoing.map { |row| row[:step] } + reached.keys + stopped.keys.map(&:first)).compact.uniq
         declared = klass ? klass.workflow_steps.entries.map { |entry| declared_step(entry) } : []
         extra = (seen - declared.map { |entry| entry[:name] }).sort_by do |name|
           [reached.dig(name, :position) || Float::INFINITY, stats.dig(name, :first_seen_at)&.to_f || Float::INFINITY, name]
         end
-        declared + extra.map { |name| { name: name, kind: nil, removed: false, declared: false } }
+        declared + extra.map { |name| { name: name, kind: nil, removed: false, declared: false, wait_timeout: nil } }
       end
 
       def declared_step(entry)
@@ -63,7 +63,15 @@ module Pgbus
                elsif entry.waits_for_signal? then "signal"
                else "step"
                end
-        { name: entry.name, kind: kind, removed: entry.removed?, declared: true }
+        { name: entry.name, kind: kind, removed: entry.removed?, declared: true, wait_timeout: wait_timeout(entry) }
+      end
+
+      # A signal step's wait_timeout: in seconds, "dynamic" for a per-run one
+      # (issue #574), nil without one.
+      def wait_timeout(entry)
+        return nil if entry.removed?
+
+        entry.dynamic_wait_timeout? ? "dynamic" : entry.wait_timeout
       end
 
       def step(entry, stats, ongoing)

data/lib/pgbus/web/workflow_state.rb

@@ -51,9 +51,12 @@ module Pgbus
         return ["waiting", "waiting_step", { step: step }] unless row[:waiting_for]
 
         args = { signal: row[:waiting_for], ago: row[:waiting_since] }
-        return ["waiting", "waiting_signal", args] unless row[:timeout_at]
+        return signal_deadline(row, args.merge(time: row[:timeout_at])) if row[:timeout_at]
+        # A per-run wait_timeout: reported once under on_timeout: :notify,
+        # then left without a deadline (issue #574).
+        return ["waiting", "waiting_signal_late_no_deadline", args.merge(late: row[:late_since])] if row[:late_since]
 
-        signal_deadline(row, args.merge(time: row[:timeout_at]))
+        ["waiting", "waiting_signal", args]
       end
 
       # An on_timeout: :notify deadline sends a late notice and the wait goes

data/lib/pgbus/workflow/instance.rb

@@ -94,6 +94,33 @@ module Pgbus
         @timed_out == true
       end
 
+      # Inside a step (its guards and its body): true when this attempt holds
+      # a signal before its gate runs: signal! woke the step, or an earlier
+      # attempt of it took one and reattempted or failed into a pause. False
+      # on an attempt that has not waited yet (even one whose gate then takes
+      # a buffered signal), after an on_timeout: :run wake, and in a step
+      # without wait_for:. The same answer for the whole attempt.
+      def woken?
+        step_context!(:woken?)
+        @woken = !@signal_peek&.held.nil? if @woken.nil?
+        @woken
+      end
+
+      # Inside a step (its guards and its body): true when the gate runs this
+      # attempt with a signal: the one it holds (woken?), or a pending one its
+      # wait_for: matcher takes. The guard for "skip a wait the record already
+      # passed", which neither skips a signalled step nor leaves its signal
+      # pending. False after an on_timeout: :run wake (the gate takes no
+      # signal then) and in a step without wait_for:. Reads only: the gate
+      # claims the signal after the guards.
+      #
+      #   step :await_shipped, skip_if: -> { subject.shipped? && !signal_ready? }, wait_for: :shipped do … end
+      def signal_ready?
+        step_context!(:signal_ready?)
+        @signal_ready = !@signal_peek&.ready.nil? if @signal_ready.nil?
+        @signal_ready
+      end
+
       # Deliver a signal to this run. Stored under the run's lock; a step
       # waiting for it (wait_for:) is woken at once, otherwise it waits,
       # pending, for the step that claims it. With an idempotency_key a
@@ -164,19 +191,25 @@ module Pgbus
         @guarding = false
       end
 
-      # Used by the StepJob only.
-      def enter_step(context)
+      # Used by the StepJob only. +signals+ is the attempt's SignalPeek, which
+      # woken? and signal_ready? read until the gate answers them.
+      def enter_step(context, signals: nil)
         @step_context = context
+        @signal_peek = signals
         @output_values = nil
         @pending_output = nil
         @received_signal = nil
         @timed_out = false
+        @woken = nil
+        @signal_ready = nil
       end
 
       # Used by the StepJob's signal gate only.
-      def enter_wait(signal:, timed_out:)
+      def enter_wait(signal:, timed_out:, woken: false)
         @received_signal = signal
         @timed_out = timed_out
+        @woken = woken
+        @signal_ready = !signal.nil?
       end
     end
   end

data/lib/pgbus/workflow/runner.rb

@@ -68,11 +68,11 @@ module Pgbus
 
       # --- start! and rerun! --------------------------------------------
 
-      def start(klass, subject:, arguments:, idempotency_key: nil)
+      def start(klass, subject:, arguments:, idempotency_key: nil, actor: DEFAULT_ACTOR, reason: nil)
         attrs = run_attributes(klass, idempotency_key: idempotency_key)
                 .merge(Payload.subject_attributes(subject))
                 .merge(arguments: Payload.dump(arguments, what: "arguments of #{klass.name}"))
-        insert_run(klass, attrs, actor: DEFAULT_ACTOR)
+        insert_run(klass, attrs, actor: actor, reason: reason)
       end
 
       # A finished or cancelled run started again: same subject and

data/lib/pgbus/workflow/signal_peek.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # What a wait_for: step's attempt holds and what its gate would run it
+    # with (issue #572), read without claiming anything. The StepJob builds
+    # one per attempt: the step readers woken? and signal_ready? read it in
+    # the guards, and the gate decides with the same one, so the gate takes
+    # exactly the signal signal_ready? promised. All of it runs under the
+    # run's row lock, so each answer is looked up (and a matcher run) once.
+    class SignalPeek
+      def initialize(record, step, definition, now: Time.current)
+        @record = record
+        @step = step
+        @definition = definition
+        @now = now
+      end
+
+      # The claimed signal the step holds (signal! woke it, or an earlier
+      # attempt took one and reattempted or paused), or nil. Always nil for a
+      # step without wait_for:.
+      def held
+        return @held if defined?(@held)
+
+        @held = waits? ? WorkflowSignal.held_by_step(@record.workflow_id, @step.step_name) : nil
+      end
+
+      # The sweep woke this attempt with on_timeout: :run: its body runs
+      # without a signal (Signals.timed_out?).
+      def timed_out? = Signals.timed_out?(@step, @now)
+
+      # The signal the gate runs this attempt with: the one the step holds,
+      # else the oldest pending one its matcher takes. nil when the wait timed
+      # out (the body runs without one), when nothing matches (the step
+      # parks), and for a step without wait_for:.
+      def ready
+        return @ready if defined?(@ready)
+
+        @ready = waits? && !timed_out? ? held || Signals.match(@record, @definition.wait_for) : nil
+      end
+
+      private
+
+      def waits? = @definition.waits_for_signal?
+    end
+  end
+end

data/lib/pgbus/workflow/signals.rb

@@ -12,6 +12,8 @@ module Pgbus
     # lock: a signal this step already holds (woken by signal!, or claimed by
     # an earlier attempt that reattempted or paused on a failure), else the
     # oldest pending one its matcher takes, else the step parks as waiting.
+    # The guards run first; woken? and signal_ready? (issue #572) show them
+    # what the gate holds and would take, through SignalPeek, claiming nothing.
     #
     # A claimed signal is consumed when its step ends, except when that
     # attempt reattempts or fails into a pause: the next attempt runs with it.
@@ -38,23 +40,38 @@ module Pgbus
       end
 
       # The gate of a wait_for: step. True when the body runs (with a signal,
-      # or timed out), false when the step parked. Sets received_signal and
-      # timed_out? on +workflow+.
-      def gate(record, step, definition, workflow, now: Time.current)
-        if timed_out?(step, now)
+      # or timed out), false when the step parked. Sets received_signal,
+      # timed_out?, woken? and signal_ready? on +workflow+. Which signal it
+      # takes is SignalPeek#ready: given the attempt's +peek+ (the StepJob
+      # passes the one its guards read), the very answer signal_ready? gave.
+      def gate(record, step, definition, workflow, now: Time.current, peek: nil)
+        peek ||= SignalPeek.new(record, step, definition, now: now)
+        if peek.timed_out?
           workflow.send(:enter_wait, signal: nil, timed_out: true)
           return true
         end
 
-        signal = WorkflowSignal.held_by_step(record.workflow_id, step.step_name) || match(record, definition.wait_for)
-        return park(record, step, definition, now) unless signal
+        signal = peek.ready
+        return park(record, step, definition, workflow, now) unless signal
 
+        woken = !peek.held.nil?
         claim!(record, step, signal, actor: Runner::SYSTEM_ACTOR) if signal.status == "pending"
         step.update_columns(signal_id: signal.id) unless step.signal_id == signal.id
-        workflow.send(:enter_wait, signal: signal, timed_out: false)
+        workflow.send(:enter_wait, signal: signal, timed_out: false, woken: woken)
         true
       end
 
+      # An attempt that ended before its gate (cancel_if, skip_if, a guard
+      # that raised, a removed_step) records +held+, the signal the step
+      # holds, on its row, so settle treats it as for any attempt: consumed
+      # when the step ends, kept when it reattempts or fails into a pause. A
+      # post-reattempt row carries no signal_id until its gate runs. A
+      # pending signal stays pending: no step took it, and a later wait_for:
+      # step may.
+      def adopt_held(step, held)
+        step.update_columns(signal_id: held.id) if held && step.signal_id != held.id
+      end
+
       # The step's attempt ended (StepOutcome.apply): consume the signal it
       # holds, unless the next attempt runs with it.
       def settle(step, status, column, now:)
@@ -116,14 +133,18 @@ module Pgbus
         nil
       end
 
-      def park(record, step, definition, now) # rubocop:disable Naming/PredicateMethod -- the gate's false: the body does not run
-        timeout_at = definition.wait_timeout && (now + definition.wait_timeout)
+      # A per-run wait_timeout: is evaluated here, before Waiting.park! writes
+      # the waiting state: one that raises (an invalid return raises
+      # ArgumentError) leaves the attempt in_progress for the step's exception
+      # policies; nil parks it without a deadline.
+      def park(record, step, definition, workflow, now) # rubocop:disable Naming/PredicateMethod -- the gate's false: the body does not run
+        timeout_at = definition.timeout_at_for(workflow, now)
         Waiting.park!(record, step, now: now, wait_for: definition.wait_for_name, timeout_at: timeout_at)
         false
       end
 
       # This attempt waited, holds no signal, and its wait_timeout passed: the
-      # sweep woke it with on_timeout: :run.
+      # sweep woke it with on_timeout: :run (SignalPeek#timed_out?).
       def timed_out?(step, now)
         !step.waiting_since.nil? && step.signal_id.nil? && !step.timeout_at.nil? && step.timeout_at <= now + 1
       end

data/lib/pgbus/workflow/step_definition.rb

@@ -15,8 +15,11 @@ module Pgbus
       # (job_options:) may set. Anything else raises at class load.
       JOB_OPTIONS = %i[queue priority wait wait_until].freeze
 
+      # wait_timeout is the static wait_timeout: in seconds (nil for a per-run
+      # one); wait_timeout_callable the per-run one as given, a lambda or a
+      # method name (issue #574).
       attr_reader :name, :body, :wait, :skip_if, :job_options, :timeout, :exception_policies,
-                  :wait_for, :wait_for_name, :wait_timeout, :on_timeout
+                  :wait_for, :wait_for_name, :wait_timeout, :wait_timeout_callable, :on_timeout
 
       def self.validate_job_options!(options)
         raise ArgumentError, "job_options: must be a Hash, got #{options.inspect}" unless options.is_a?(Hash)
@@ -104,6 +107,44 @@ module Pgbus
         result ? true : false
       end
 
+      # True when wait_timeout: is a lambda or a method name, evaluated per run.
+      def dynamic_wait_timeout? = !wait_timeout_callable.nil?
+
+      # The timeout_at of the step parking now on +workflow+: now plus a
+      # static wait_timeout:, what a per-run one returns (a deadline already
+      # past is now, so the next sweep applies on_timeout), or nil.
+      def timeout_at_for(workflow, now)
+        return now + wait_timeout if wait_timeout
+        return nil unless dynamic_wait_timeout?
+
+        deadline = resolve_wait_timeout(workflow)
+        deadline.is_a?(Time) ? [deadline, now].max : deadline && (now + deadline)
+      end
+
+      # What the per-run wait_timeout: returns on +workflow+: a Time (an
+      # absolute deadline), seconds from now, or nil (no timeout). It runs as
+      # a guard does (a flow-control verb raises NotInStep), in a savepoint:
+      # a query of its own that fails in the database must not abort the
+      # run's transaction, which the step's outcome is written in. Anything
+      # else raises ArgumentError, as an error it raises goes up, for the
+      # step's exception policies.
+      def resolve_wait_timeout(workflow)
+        callable = wait_timeout_callable
+        value = WorkflowEntry.transaction(requires_new: true) do
+          workflow.send(:guarding) { callable.is_a?(Symbol) ? workflow.send(callable) : workflow.instance_exec(&callable) }
+        end
+        return nil if value.nil?
+        if value.is_a?(Numeric) || self.class.duration?(value)
+          return self.class.seconds(value, "wait_timeout (step #{name})", positive: true)
+        end
+
+        time = value.to_time if value.respond_to?(:to_time) && !value.is_a?(String)
+        return time if time.is_a?(Time)
+
+        raise ArgumentError, "wait_timeout: of step #{name} must return a Time, a Duration, a number of seconds or nil, " \
+                             "got #{value.inspect}"
+      end
+
       private
 
       def assign_wait(wait_for, wait_timeout, on_timeout)
@@ -112,8 +153,9 @@ module Pgbus
         raise ArgumentError, "on_timeout: needs wait_for: and wait_timeout:" if !on_timeout.nil? && (@wait_for.nil? || wait_timeout.nil?)
         raise ArgumentError, "wait_timeout: needs wait_for: (it bounds the wait for a signal)" if wait_timeout && @wait_for.nil?
 
-        @wait_timeout = self.class.seconds(wait_timeout, "wait_timeout", positive: true)
-        @on_timeout = @wait_timeout && normalize_on_timeout(on_timeout.nil? ? :pause! : on_timeout)
+        @wait_timeout_callable = wait_timeout if wait_timeout.is_a?(Symbol) || wait_timeout.is_a?(Proc)
+        @wait_timeout = @wait_timeout_callable ? nil : self.class.seconds(wait_timeout, "wait_timeout", positive: true)
+        @on_timeout = (@wait_timeout || @wait_timeout_callable) && normalize_on_timeout(on_timeout.nil? ? :pause! : on_timeout)
       end
 
       def normalize_on_timeout(value)

data/lib/pgbus/workflow/step_execution.rb

@@ -13,7 +13,8 @@ module Pgbus
     #    heartbeat is on: its worker died, and the stall action applies now.
     # 2. Guards, still under the lock: the class or the step no longer
     #    defined (pause with StepNotDefined, or skip a removed_step),
-    #    cancel_if, skip_if.
+    #    cancel_if, skip_if (which read woken? and signal_ready? through the
+    #    attempt's SignalPeek), then a wait_for: step's signal gate.
     # 3. The body, outside any transaction, inside `catch` for the
     #    flow-control verbs and `rescue StandardError` for the policies.
     # 4. The outcome, under the lock again (StepOutcome).
@@ -21,7 +22,9 @@ module Pgbus
     # Whatever the step's outcome, the job itself completes normally: the
     # step row and the pgbus.workflow.* events carry the truth.
     class StepExecution
-      Claim = Data.define(:record, :step, :klass, :definition, :workflow, :guard_error)
+      # +adopt_held+: a guard raised before the gate, so the signal the step
+      # holds is put on this attempt's row before its outcome (Signals.adopt_held).
+      Claim = Data.define(:record, :step, :klass, :definition, :workflow, :guard_error, :adopt_held)
 
       def initialize(step_id, delivery: Pgbus::ActiveJob::Delivery.current, config: Pgbus.configuration)
         @step_id = step_id
@@ -103,15 +106,23 @@ module Pgbus
         return undefined!(record, step, notes, "#{record.workflow_class} is not a Pgbus::Workflow class any more") unless klass
 
         unless definition
-          return skip!(record, step, notes, klass) if klass.workflow_steps.removed?(step.step_name)
+          if klass.workflow_steps.removed?(step.step_name)
+            # The definition is gone, so whether it waited is unknown: look for a
+            # held signal only where the signal schema exists.
+            Signals.adopt_held(step, WorkflowSignal.held_by_step(record.workflow_id, step.step_name)) if Sweep.waiting_ready?
+            return skip!(record, step, notes, klass)
+          end
 
           return undefined!(record, step, notes, "#{klass.name} has no step #{step.step_name} " \
                                                  "(declare `removed_step :#{step.step_name}` to skip it)")
         end
 
         workflow = klass.new(record)
-        workflow.send(:enter_step, StepContext::Attempt.new(step_id: step.id, step_name: step.step_name, attempt: step.attempt))
-        claim = Claim.new(record: record, step: step, klass: klass, definition: definition, workflow: workflow, guard_error: nil)
+        peek = SignalPeek.new(record, step, definition)
+        workflow.send(:enter_step, StepContext::Attempt.new(step_id: step.id, step_name: step.step_name, attempt: step.attempt),
+                      signals: peek)
+        claim = Claim.new(record: record, step: step, klass: klass, definition: definition, workflow: workflow, guard_error: nil,
+                          adopt_held: false)
         begin
           verdict = workflow.send(:guarding) do
             next FlowControl::Outcome.cancel if cancel?(klass, workflow)
@@ -119,20 +130,23 @@ module Pgbus
             FlowControl::Outcome.skip if definition.skip?(workflow)
           end
         rescue StandardError => e
-          return claim.with(guard_error: e)
+          return claim.with(guard_error: e, adopt_held: definition.waits_for_signal?)
+        end
+        if verdict
+          Signals.adopt_held(step, peek.held)
+          return outcome!(record, step, notes, klass, verdict)
         end
-        return outcome!(record, step, notes, klass, verdict) if verdict
 
-        gate(record, step, definition, workflow, claim)
+        gate(record, step, definition, workflow, claim, peek)
       end
 
       # A wait_for: step runs only with a signal (or once its wait timed
       # out); without one it parks and this delivery ends. A matcher that
       # raises is handed to the exception policies, like a guard.
-      def gate(record, step, definition, workflow, claim)
+      def gate(record, step, definition, workflow, claim, peek)
         return claim unless definition.waits_for_signal?
 
-        Signals.gate(record, step, definition, workflow) ? claim : nil
+        Signals.gate(record, step, definition, workflow, peek: peek) ? claim : nil
       rescue StandardError => e
         claim.with(guard_error: e)
       end
@@ -185,6 +199,9 @@ module Pgbus
           next park_fan_out(record, claim, outcome, notes) if outcome&.action == :fan_out
 
           notes.report(decision.handler_error, handler_context(claim)) if decision&.handler_error
+          # Here rather than in the claim's transaction, which the statement
+          # a guard failed on may have aborted.
+          Signals.adopt_held(claim.step, SignalPeek.new(record, claim.step, claim.definition).held) if claim.adopt_held
           StepOutcome.apply(record, claim.step, outcome, notes: notes, error: error, output: claim.workflow.pending_output,
                                                          report: decision ? decision.report : true, duration: duration,
                                                          klass: claim.klass)

data/lib/pgbus/workflow/wait_timeout.rb

@@ -14,7 +14,8 @@ module Pgbus
     #            received_signal nil and timed_out? true
     #   :notify  only the event and the instrumentation (issue #565): the
     #            same attempt keeps waiting and timeout_at moves to its next
-    #            deadline, one wait_timeout on (see next_deadline)
+    #            deadline, one wait_timeout on (see next_deadline); a per-run
+    #            wait_timeout: is evaluated again for it (see notify_deadline)
     #
     # A signal that arrives after the timeout fired stays pending, like any
     # signal no step waits for, except under :notify, whose step still waits
@@ -56,12 +57,12 @@ module Pgbus
                                                            timeout_at: step.timeout_at&.utc&.iso8601(3) }.compact)
         notes.instrument("pgbus.workflow.wait_timed_out",
                          Runner.payload_for(record, step_name: step.step_name, attempt: step.attempt, action: action.to_s))
-        apply(record, step, action, notes: notes, now: now, wait_timeout: definition&.wait_timeout)
+        apply(record, step, action, notes: notes, now: now, definition: definition)
         action
       end
 
-      def apply(record, step, action, notes:, now:, wait_timeout: nil)
-        return notify!(step, wait_timeout, now: now) if action == :notify
+      def apply(record, step, action, notes:, now:, definition: nil)
+        return notify!(record, step, definition, notes: notes, now: now) if action == :notify
         return Waiting.wake!(record, step, now: now, timeout_at: [step.timeout_at, now].compact.min) if action == :run
 
         error = action == :pause! ? timed_out_error(step, now) : nil
@@ -69,12 +70,42 @@ module Pgbus
       end
 
       # The run and the step row stay as they are (no outcome, no StepJob);
-      # only timeout_at moves.
-      def notify!(step, wait_timeout, now:)
-        timeout_at = next_deadline(step.timeout_at, wait_timeout, now)
+      # only timeout_at moves. A per-run wait_timeout: that raises here, or
+      # returns what is no deadline, pauses the run with that error: the
+      # sweep holds the run's row lock, under which no on_exception block
+      # may run, so the exception policies do not apply.
+      def notify!(record, step, definition, notes:, now:)
+        timeout_at = notify_deadline(record, step, definition, now)
+      rescue StandardError => e
+        Waiting.resolve!(record, step, FlowControl::Outcome.pause, notes: notes, error: e)
+      else
         step.timeout_at = timeout_at if WorkflowStep.move_deadline!(step.id, timeout_at: timeout_at).positive?
       end
 
+      # The next deadline of a :notify wait. A per-run wait_timeout: (issue
+      # #574) is evaluated again: a Time after now is the next deadline, a
+      # duration moves it one period on as a static one does, and nil or a
+      # Time not after now leaves the wait without a deadline (it was
+      # reported once and keeps waiting).
+      def notify_deadline(record, step, definition, now)
+        return next_deadline(step.timeout_at, definition.wait_timeout, now) unless definition.dynamic_wait_timeout?
+
+        deadline = definition.resolve_wait_timeout(instance_for(record, step))
+        case deadline
+        when nil then nil
+        when Time then deadline if deadline > now
+        else next_deadline(step.timeout_at, deadline, now)
+        end
+      end
+
+      # The workflow instance a per-run wait_timeout: is evaluated on, as the
+      # StepJob builds it for the attempt.
+      def instance_for(record, step)
+        record.workflow_klass.new(record).tap do |workflow|
+          workflow.send(:enter_step, StepContext::Attempt.new(step_id: step.id, step_name: step.step_name, attempt: step.attempt))
+        end
+      end
+
       # The first deadline after +now+ on the wait's wait_timeout grid: one
       # wait_timeout on when the sweep is within a period of the deadline
       # (and for expire_wait ahead of it). A sweep that missed several

data/lib/pgbus/workflow.rb

@@ -111,12 +111,18 @@ module Pgbus
       #
       #   SignupWorkflow.start!(user, plan: "pro")    # arguments["plan"]
       #   CheckoutWorkflow.start!(order, idempotency_key: "checkout-#{order.id}")
+      #   ReportWorkflow.start!(actor: "alice", reason: "monthly close")
       #
-      # +idempotency_key+ is reserved: with one, a second start! with the same
-      # key returns the first run (any status) with duplicate_start? true.
-      # Raises AlreadyRunning when the subject already has an ongoing run.
-      def start!(subject = nil, idempotency_key: nil, **arguments)
-        Runner.start(self, subject: subject, arguments: arguments, idempotency_key: idempotency_key)
+      # +idempotency_key+, +actor+ and +reason+ are reserved and never reach
+      # the arguments. With an idempotency_key, a second start! with the same
+      # key returns the first run (any status) with duplicate_start? true and
+      # records nothing. +actor+ (default "app") and +reason+ go on the
+      # started event, and the actor on the first step_scheduled, as on every
+      # outside verb. Raises AlreadyRunning when the subject already has an
+      # ongoing run.
+      def start!(subject = nil, idempotency_key: nil, actor: nil, reason: nil, **arguments)
+        Runner.start(self, subject: subject, arguments: arguments, idempotency_key: idempotency_key,
+                           actor: actor || Runner::DEFAULT_ACTOR, reason: reason)
       end
 
       # The run with this workflow_id, as an instance of the class that

data/sig/pgbus.rbs

@@ -56,6 +56,49 @@ module Pgbus
     end
   end
 
+  # Partial: only the readers a workflow step's guards and body use to see
+  # its signal (issue #572), and a step definition's wait_timeout: (issue
+  # #574). The rest of Workflow is not covered by spec/pgbus/rbs_spec.rb yet.
+  class Workflow
+    include Instance
+
+    class Error < Pgbus::Error
+    end
+
+    # A step reader (woken?, signal_ready?, ...) called outside a step.
+    class NotInStep < Error
+    end
+
+    module Instance
+      # The Pgbus::WorkflowSignal a wait_for: step took, or nil when its wait timed out.
+      def received_signal: () -> untyped
+      # The body runs because the wait timed out (on_timeout: :run).
+      def timed_out?: () -> bool
+      # This attempt holds a signal before its gate: signal! woke it, or an
+      # earlier attempt took one and reattempted or paused.
+      def woken?: () -> bool
+      # The gate runs this attempt with a signal: the held one, or a pending
+      # one its wait_for: matcher takes.
+      def signal_ready?: () -> bool
+    end
+
+    # One declared step (klass.workflow_steps.fetch(:name)): its wait_timeout:.
+    class StepDefinition
+      # A static wait_timeout: in seconds; nil without one, or for a per-run one.
+      def wait_timeout: () -> Numeric?
+      # A per-run wait_timeout: as declared: a method name or a lambda.
+      def wait_timeout_callable: () -> (Symbol | Proc)?
+      # wait_timeout: is a method name or a lambda, evaluated per run.
+      def dynamic_wait_timeout?: () -> bool
+      # The timeout_at of the step parking at +now+ on +workflow+; nil for no timeout.
+      # +now+ and the result are a Time or an ActiveSupport::TimeWithZone (Time.current
+      # in an app with a time zone), which sig/ does not declare: untyped.
+      def timeout_at_for: (Workflow workflow, untyped now) -> untyped
+      # What a per-run wait_timeout: returns on +workflow+: a deadline, seconds from now, or nil.
+      def resolve_wait_timeout: (Workflow workflow) -> (Time | Numeric)?
+    end
+  end
+
   def self.configuration: () -> Configuration
   def self.configuration_snapshot: () -> Configuration::Snapshot
   def self.configure: () { (Configuration) -> void } -> Configuration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.20.1
+  version: 0.21.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -588,6 +588,7 @@ files:
 - lib/pgbus/workflow/removed_step.rb
 - lib/pgbus/workflow/runner.rb
 - lib/pgbus/workflow/signal_matcher.rb
+- lib/pgbus/workflow/signal_peek.rb
 - lib/pgbus/workflow/signals.rb
 - lib/pgbus/workflow/states.rb
 - lib/pgbus/workflow/step_context.rb