A poll reports every terminal run, cancellation included
The rule
- A poll reports runs in any terminal status, not only successful and failed ones (a cancelled run is terminal and is reported), so a polling caller always reaches an end state.
- A run that is genuinely paused appears in no poll until it resumes or reaches a terminal status.
- A backlog may need more than one poll to drain, and nothing is dropped on the way.
What it means
A poll exists so a caller can eventually reach an end state for every run it is watching, so the terminal statuses it reports cannot stop at completed and failed. A cancelled run is just as terminal, and leaving it out of what a poll reports would leave a caller who cancelled a run waiting forever for a verdict that story never delivers. The rule draws the boundary from both sides: a run that is genuinely still paused belongs in no poll response — reporting it there would tell a caller to stop watching a run that is going to resume — while every run that has actually finished, however it finished, belongs in one.
Example
One externally invoked run is recorded in each terminal status, each named after its status; a single poll reports all three (sorted here for reading).
["terminal_cancelled", "terminal_completed", "terminal_failed"]