Fix #21734: Use wildcard in zombie flow detection docs for custom state names

[devin-ai-integration]

closes #21734

Updates the zombie flow detection guide to use a prefect.flow-run.* wildcard in the automation's expect set instead of listing individual terminal state names (Completed, Failed, Cancelled, Crashed).

Flow run event names are based on the state's name, not its type. This means a flow finishing in a COMPLETED state with a custom name (e.g., Completed(name="SuccessfullyProcessed")) emits prefect.flow-run.SuccessfullyProcessed, which wouldn't match the previously documented expect set. Using the wildcard ensures the automation works correctly regardless of custom state names.

The wildcard approach is also simpler and more robust — any flow run event (heartbeat or state change) resets the proactive trigger timer, which is the correct behavior for zombie detection: if a flow is emitting any events at all, it's not a zombie.

Also adds a new "Custom state names" section that:

• Explains how flow run event names are derived from state names, not types
• Documents the alternative approach of explicitly listing custom state names in the expect set for finer-grained control
• Warns that missing names cause false-positive zombie detections

Checklist

• This pull request references any related issue by including "closes <link to issue>"
• If this pull request adds new functionality, it includes unit tests that cover the changes
• If this pull request removes docs files, it includes redirect settings in mint.json.
• If this pull request adds functions or classes, it includes helpful docstrings.

Link to Devin session: https://app.devin.ai/sessions/33a9bba0680f42b490d3b072c3e06f2e

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
prefect-oss	🟢 Ready	View Preview	Apr 30, 2026, 2:08 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[NicholasPini]

This doesn't fix the issue in #21734

Matching a wild card would mean matching ANY state, which means that no detection of zombie flow is made. What one should be able to do is specify state types in the expect block of an automation trigger, so that I can expect any COMPLETED state type regardless of its name.

[desertaxle]

@NicholasPini, matching any state won't break zombie detection; it will broaden the conditions necessary to disarm the automation after each heartbeat event. Every heartbeat event arms the automation and may also disarm the previously armed proactive trigger.

The proposed update to the automation will improve behavior for flow runs with retries and long retry delays since those flows will transition to SCHEDULED/AwaitingRetry and stop emitting heartbeat events. The current version of the automation may cause that flow to get marked as crashed because AwaitingRetry isn't included in expect.

Another possible solution is to include custom state names in your automation for finer-grained control. I'm working on a design to bring zombie flow run detection directly into the orchestration engine, so I think updating the documentation to show how to modify this automation for different use cases is a reasonable short-term solution.