fix(workflows): correct restored-session resume notices

[lavaman131]

Summary

Correct restored-session workflow resume notices so they use the same durable eligibility rules as backend discovery, the session catalog, and runtime dispatch. This preserves the notice introduced by #1726 while ensuring every genuinely resumable root workflow is surfaced and stale or non-resumable metadata is omitted.

Changes

• centralize durable resume eligibility across backend listing, session scanning, targeted runtime validation, and startup/resume notices
• surface failed and blocked workflows by default when resumable metadata is absent, excluding them only when resumable: false
• require a durable checkpoint or pending prompt for running and paused workflow notices
• exclude nested child workflows from user-facing resume notices
• parse current custom entries plus legacy direct and payload-wrapped checkpoint metadata
• add table-driven status/resumability regressions and coverage for latest-state selection, legacy shapes, and nested workflows
• document notice behavior, retention/failure semantics, and the corrected eligibility rules in the user guide and Unreleased changelog

Relationship to #1726

This PR is based on and supersedes/corrects #1726. That PR's notice filter omitted failed workflows when persisted metadata did not contain resumable: true, even though durable resume semantics intentionally treat failed and blocked workflows as resumable unless they are explicitly marked resumable: false.

Validation

• AGENT=1 bun test test/unit/resumable-workflow-notices.test.ts test/unit/durable-backend.test.ts test/unit/durable-resume-catalog.test.ts test/unit/durable-resume-runtime.test.ts — 81 passed
• AGENT=1 bun test test/unit/extension.test.ts test/unit/workflow-lifecycle-notifications.test.ts test/unit/workflow-lifecycle-notifications-01.test.ts test/unit/workflow-lifecycle-notifications-02.test.ts — 46 passed
• bun run test:unit — passed via commit and push hooks
• bun run typecheck — passed
• bun run lint — passed
• bun run check:file-length — passed
• git diff --check — passed

Fixes #1722

Greptile Summary

This PR makes restored-session workflow resume notices use the same durable eligibility rules as runtime resume discovery. The main changes are:

• Centralized durable resume eligibility for root workflows.
• Applied authoritative backend state checks to catalog scanning, runtime validation, and startup/resume notices.
• Included failed and blocked workflows by default unless resumable: false is set.
• Required durable progress for running and paused workflow notices.
• Added tests for stale cache entries, legacy checkpoint shapes, nested workflow exclusion, and status/resumability rules.
• Updated workflow docs and the Unreleased changelog.

Confidence Score: 5/5

Safe to merge with low risk.

The update is narrowly scoped and replaces duplicated eligibility checks with one shared predicate. Runtime resume validation now uses authoritative backend state before dispatch. Tests cover the changed status, stale cache, legacy shape, and nested workflow paths.

No files require special attention.

T-Rex Logs

What T-Rex did

• The Bun test suite was executed with Bun 1.3.10 and the results were saved to a log, which shows 85 pass, 0 fail, ran 85 tests across 4 files, and an exit code of 0.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
packages/workflows/src/durable/resume-eligibility.ts	Introduces the shared root-workflow durable resume eligibility predicate used across discovery, validation, and notices.
packages/workflows/src/durable/resume-runtime.ts	Validates resume attempts against authoritative backend handles and suppresses stale session-cache entries with shared eligibility rules.
packages/workflows/src/extension/extension-lifecycle.ts	Adds startup/resume notices by intersecting restored session checkpoint references with the authoritative durable resume catalog.
packages/workflows/src/shared/resumable-workflow-notices.ts	Extracts current and legacy durable checkpoint references from session entries and filters them through authoritative catalog state.
test/unit/resumable-workflow-lifecycle.test.ts	Adds lifecycle tests for notice emission, stale cache suppression, terminal state suppression, and host-entry failure handling.
test/unit/resumable-workflow-notices.test.ts	Adds table-driven notice tests for statuses, resumability flags, stale metadata, legacy entry shapes, and nested workflows.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Host as Session start/resume
participant Manager as Session manager
participant Runtime as Durable resume runtime
participant Backend as Durable backend
participant Notice as Notice filter
participant UI as User notification

Host->>Manager: get restored session entries
Host->>Runtime: prepareDurableResumable()
Runtime->>Backend: hydrate/list resumable workflows
Backend-->>Runtime: authoritative eligible catalog
Runtime-->>Host: catalog entries
Host->>Notice: findResumableWorkflowNotices(entries, catalog)
Notice->>Notice: keep session workflow ids with durable eligibility
Notice-->>Host: root resumable workflow notices
Host->>UI: notify /workflow resume commands

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Host as Session start/resume
participant Manager as Session manager
participant Runtime as Durable resume runtime
participant Backend as Durable backend
participant Notice as Notice filter
participant UI as User notification

Host->>Manager: get restored session entries
Host->>Runtime: prepareDurableResumable()
Runtime->>Backend: hydrate/list resumable workflows
Backend-->>Runtime: authoritative eligible catalog
Runtime-->>Host: catalog entries
Host->>Notice: findResumableWorkflowNotices(entries, catalog)
Notice->>Notice: keep session workflow ids with durable eligibility
Notice-->>Host: root resumable workflow notices
Host->>UI: notify /workflow resume commands

Loading

_{Reviews (3): Last reviewed commit: "Merge origin/main into fix/pr-1726-resum..." | Re-trigger Greptile}

[mintlify]

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

Project	Status	Preview	Updated (UTC)
bastani	🟢 Ready	View Preview	Jul 12, 2026, 6:35 AM

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