fix(flow): the heartbeat recovers a missed signal instead of rolling forever

[rubenvdlinde]

The defect

A UserTask's completion signal was refused on the acceptance rig — [FlowRunSignalService] Refused a signal: the actor is not the awaiting step's assignee, because the assignee group did not exist at signal time. The suspended run's 30-minute heartbeat then fired, re-suspended, and never advanced: resume_at rolled 08:07 → 08:37 → … indefinitely, while the task sat completed and the group had long since been created.

The heartbeat exists precisely to recover a missed signal. It recovered nothing.

The root cause was not the node

UserTaskNode has always re-read its task on re-entry and applied the outcome when terminal. What wedged is upstream:

persistResult() dropped every parked node's resume slot whenever a pass ended anything but suspended. FlowResumeState::storableWhen(suspended:) read NOT-SUSPENDED as "nothing left to continue from" — which conflates it with TERMINAL. A pass legitimately ends queued while a node parked in an earlier pass is still waiting: the in-request advance of a sibling branch (FlowTaskBridge::continueRun() → advanceStream()) finalises queued whenever other enabled work remains, and a claim refused on contention does the same.

The parked node then lost the uuid of the task it was waiting on. Its next wake found an empty slot and — correctly, by its own idempotency guard — created a new task. From that moment:

• the original task's completion could never address the node's slot, and its signal was refused against the new slot's recorded assignee — the refusal observed on the rig;
• every heartbeat re-read the new, still-open task and re-suspended, rolling resume_at forever;
• a duplicate task sat in somebody's inbox.

Recovery semantics

1. Slots survive every live pass end. storableWhen() keeps the per-node slots for any non-terminal status (suspended, queued, running) and drops them only on a terminal run. persistResult() derives that from FlowRun::TERMINAL, in a new keepResumeSlots() that carries the reasoning.
2. A recovered delivery is audited. When a task-waiting node reads its task terminal with no signal in hand (the completion's wake never arrived), it records heartbeat-recovered on the task's audit through FlowTaskBridge::recordHeartbeatRecovery(), attributed to the task's completedBy — the fact recorded is that person's answer arriving late, not the cron job acting. Best-effort: an audit failure never un-recovers the run. The guarded signal seam already records the refusal; this is the other half of that trail.
3. No second delivery mechanism. The wake, the node's re-read and the outcome application are exactly the paths that already existed. Per-node slot addressing (fix(flow): a resume answers only the node whose slot it answers, and the kill switch actually stops runs #3325) is untouched, so only the addressed node's slot recovers.

The symmetric cases, decided explicitly

• A task completed while the run was not yet suspended (the race). signal() refuses a non-suspended run, so that wake is lost. The node then parks on a non-null heartbeat, and the next wake re-reads the task — with the slot now durable, the race costs at most one heartbeat period. No pre-suspension re-check is added: a node cannot read an answer before it has parked on the question.
• A task whose sequence concluded (TaskSequenceService). A sequence drives every transition through TaskService's verbs, so the task named by the node's slot reaches its terminal state on the same row the heartbeat re-reads. Terminality is a property of that row; no sequence-specific handling is needed.

Tests

tests/Unit/Service/Flow/FlowHeartbeatRecoveryTest.php drives the real engine, dispatcher, node, stream walk, claims and commit path over in-memory mappers, so the pass-to-pass persistence that loses the slot is exercised exactly as the worker exercises it. Only the task bridge is mocked (tasks are rows in another service's table).

• the in-request advance keeps the sibling's parked slot — proven red on the unfixed storableWhen, and it is the wedge's root cause;
• the heartbeat recovers a completion whose signal was refused, with attribution and no duplicate task;
• a still-open task re-parks unchanged (askedAt not restamped);
• only the addressed node's slot recovers; the waiting sibling keeps its own task.

Plus: recovery-vs-signal audit pairs on UserTaskNodeTest and PortalTaskNodeTest, and storableWhen() live/terminal/empty cases on FlowResumeStateTest.

Full unit suite green: 19,093 tests. PHPCS, Psalm (no errors), PHPStan (no errors) and PHPMD (both rulesets) clean.

Out of scope

Runs already wedged before this fix — slot lost, duplicate task created — cannot be recovered retroactively: the original task's uuid is gone from the run. They end at the abandoned-signal reaper or by manual retry, as today.

🤖 Generated with Claude Code

[github-actions]

Quality Report — ConductionNL/openregister @ 186460b

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
check-specs		✅
test-l10n		✅
test-l10n-parity		✅
format		✅
check-schema-l10n		✅
check-l10n-js		✅
composer			✅	✅ 174/174
npm			✅	✅ 543/543
app:check-code	⏭️
info.xml	✅
REUSE	❌
PHPUnit					❌
Newman					✅
Playwright					⏭️ deferred — runs on the promotion into beta/main, not on a pull request into development
Hydra gates					✅

---

Quality workflow — 2026-09-03 10:20 UTC

Download the full PDF report from the workflow artifacts.