Called at the END of every attempt (10.1) — every outcome, with the
attempt's AttemptRecord (timing, outcome, category, the
retry-or-stop decision): a stage's own (record.kind === 'stage', under a
retry policy, a timeoutMs or a run deadline), and the calls it makes
('call', scope.$call) and outside attempts it reports ('observed')
during the stage (P2). A stage attempt fires before onStageRetry when it
is retried, and before onError / onStageExecuted for the last.
structuredError is the attempt's served error (raw included unless the
policy masked it; never for an observed attempt); absent for a success or
a pause.
Event arithmetic: one per attempt — for a stage, the number of attempts it
made plus one per call or observed attempt (filter on record.kind).
Called when a stage triggers break (early termination).
Called when a decider selects a branch. Most valuable for LLM context.
Called when a stage throws an error, with its SERVED form: for a stage's own failure that is
RedactionRule.retainStageError (the diagnostic policy applied once), elsewhere extractErrorInfo.
Called when a fork executes all children in parallel.
Called on loop iteration (back-edge traversal).
Called on linear continuation from one stage to the next.
Called when a pausable stage pauses execution.
Called when a paused stage is resumed.
Called once per top-level executor.run(), AFTER the last stage commits.
output is the retained form of the chart's return. NOT fired on pause (the run
didn't end; it suspended) or on uncaught error. Subflow-traversers do
NOT fire this event — they fire onSubflowExit.
Called once per top-level executor.run() when traversal throws a
NON-pause error, BEFORE the exception propagates to run()'s caller.
This is the TERMINAL counterpart to onRunEnd — it closes the run
boundary symmetrically so every onRunStart is followed by exactly
one of onRunEnd (clean) or onRunFailed (error). Without it, a
live monitor sees onRunStart then silence on a failed run and can't
tell "still running" from "crashed."
Errors STILL throw — this is the observable terminal signal, not a recovery mechanism (no routing, no error-subflow). Pause is NOT an error, so it does not fire this. Subflow-traversers do NOT fire it; their errors propagate to the parent and surface at the top level.
Called once per top-level executor.run(), BEFORE the first stage executes.
input is the retained form of run({input}) after schema validation;
the run's key/path redaction applies before dispatch. See FlowRunEvent.
Subflow-traversers do NOT fire this event — they fire onSubflowEntry.
Called when a selector picks a subset of children.
Called when a stage completes its main work. Fires for ALL stage
kinds ('linear', 'decider', 'fork', 'selector', 'subflow-mount')
AFTER the corresponding specialized event (onDecision, onFork,
onSelected, onSubflowEntry). For linear stages, fires after
the stage function returns.
Consumers tracking "did this stage run?" use this event uniformly
and switch on stageType for kind-specific work.
Called when an attempt at a stage with a declared retry policy failed
AND another attempt will run. Fires after that attempt's onAttempt,
after its staged writes are discarded and BEFORE the backoff wait, so a
live monitor learns "retrying in 500 ms" when the decision is made, not
after the wait.
Event arithmetic: an exhausted policy fires attempts - 1 of these and
then one onError; a retryOn that declines fires ZERO of these and one
onError. The final attempt never fires this event.
Called when entering a subflow (nested context boundary).
Called when exiting a subflow.
Called when a dynamic subflow is registered during traversal.
Returns accumulated narrative sentences in execution order.