Skip to content

Flow — Recover a failed or stuck run

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
Persona Omer (Operator)
Experience requirements FUX-04, FUX-07
Steps 4

An operator finds a failed, paused or uncertain run, reads the timeline and receipts, resolves the uncertain effect or restarts from a checkpoint.

flowchart TD
    s1["1. run-list<br/>failed, paused or uncertain?"] --> s2
    s2["2. run-timeline<br/>which attempt and receipt?"] --> s3
    s3["3. workflow-run-graph<br/>interrupt, answer a decision, or resume from a checkpoint?"] --> s4
    s4["4. alerts"]
    s1 -. "projection stale: rebuild offered" .-> x1_1["adverse 1.1"]
    s2 -. "trace backend unavailable: timeline from the projection only, drill-down degraded" .-> x2_1["adverse 2.1"]
    s3 -. "lease held by a worker: wait or reclaim after expiry" .-> x3_1["adverse 3.1"]
    s3 -. "checkpoint missing: restart the step" .-> x3_2["adverse 3.2"]
    s4 -. "uncertain tool effect alert resolved only with a confirmation receipt" .-> x4_1["adverse 4.1"]
Hold "Alt" / "Option" to enable pan & zoom

Steps

# Screen Decision point Reads Commands Adverse branches
1 run-list — Runs failed, paused or uncertain? ListRunProjections, Operations.Subscribe RebuildRunProjection projection stale: rebuild offered
2 run-timeline — Run timeline which attempt and receipt? GetRunTimeline, GetAttemptTimeline, GetWorkflowRunGraph — trace backend unavailable: timeline from the projection only, drill-down degraded
3 workflow-run-graph — Workflow run graph interrupt, answer a decision, or resume from a checkpoint? GetWorkflowRunGraph, GetAttemptTimeline, ListCheckpoints Runtime.Interrupt, Runtime.AnswerDecision lease held by a worker: wait or reclaim after expiry; checkpoint missing: restart the step
4 alerts — Alerts — ListAlerts, ListAlertRules AcknowledgeAlert, ResolveAlert, SetAlertRule uncertain tool effect alert resolved only with a confirmation receipt

Acceptance

Every step is exercised keyboard-only at 1440×900 and 390×844, in light and dark, in en and he (RTL); every adverse branch renders its state from the states catalog with words, never colour alone; a command's outcome is the server's response, never a toast.