@noetaris/harness 0.5.0 → 0.6.0

package/README.md

@@ -156,6 +156,157 @@ const resumed = run.resume(response, interruptId)
 const resumed = agent.resume(response, sessionId, interruptId)
 ```
 
+**Resume replays the interrupted step from the top.** On resume, the step that called
+`ctx.interrupt()` runs again from its first line; each `ctx.interrupt()` call it reaches
+returns the stored response instead of pausing. State updates from the paused attempt are
+not kept — a step's update is applied only when `run` returns. So any side effect a step
+performs *before* `ctx.interrupt()` (an HTTP call, a DB write, a sub agent run) happens
+again on resume. Making that safe is up to the step: guard the side effect so a replay
+skips or reuses it.
+
+**Inside a fork, only paused branches replay.** When a fork pauses, each branch is saved
+separately. On resume, a branch that already finished is not run again — its saved state
+goes straight to the join. Every branch that is still paused runs again from its paused
+step, even if the response you sent was for a different branch; a branch with no response
+yet reaches its `ctx.interrupt()` again and re-pauses. The session stays paused until
+every pending interrupt (see `agent.status(sessionId).pendingInterrupts`) is answered.
+If any branch fails, the fork fails fast: the other branches are aborted and paused
+branches are dropped. The same happens when a branch throws a graph-definition error
+(for example a signal with no matching `.on()`): the other branches are aborted, and the
+run rejects with that error only after they have stopped.
+
+**Stopping a fork.** `stop()` while a fork runs stops each branch at its next step
+boundary. What happens next depends on whether any branch is waiting on an interrupt:
+
+| At the stop | Run settles with | To continue |
+|---|---|---|
+| No branch is waiting on an interrupt | `signal: null` — a plain stop; `agent.status()` shows `paused` with no pending interrupts | `agent.run()` on the same session continues the fork: finished branches are not run again, stopped branches continue from where they stopped. `resume()` throws `NoInterruptError`. |
+| At least one branch (at any depth) is waiting on an interrupt | `signal: '$interrupt'` | `resume()` answers it and re-runs every paused branch, including the ones that were only stopped |
+
+Input passed to the `agent.run()` that continues a stopped fork is merged into the main
+state only. The branches that continue keep their own saved state and do not see it; it
+is visible from the join onward.
+
+#### Calling sub agents from a step
+
+A sub agent is just another agent with its own session. When it pauses, its `run()`
+resolves with `signal: '$interrupt'` — it does not throw — so the calling step must pass
+the interrupt up with `ctx.interrupt()` and, after resume, call the sub agent's
+`resume()`. Because the step replays, the call must be idempotent. Checking the sub
+agent's session phase is enough:
+
+```ts
+async function callSubAgent(agent: Agent, sessionId: string, input: object, ctx: any) {
+  const status = await agent.status(sessionId)
+  if (status.phase === 'completed') return loadResult(sessionId)   // your own lookup — don't run again
+  let outcome
+  if (status.phase === 'paused') {
+    const pending = status.pendingInterrupts[0]!
+    const answer = await ctx.interrupt(pending.prompt, `${sessionId}:${pending.interruptId}`)
+    outcome = await agent.resume(answer, sessionId, pending.interruptId)
+  } else {
+    outcome = await agent.run(input, { sessionId })
+  }
+  if (outcome.signal === '$interrupt') {
+    const { interruptId, prompt } = outcome.state.$interrupt
+    await ctx.interrupt(prompt, `${sessionId}:${interruptId}`)             // pauses the main agent
+  }
+  return outcome.state
+}
+```
+
+Use a stable sub agent `sessionId` (for example derived from the main `sessionId`) so a
+replay finds the same session. To run several sub agents in parallel, put each in its own
+fork branch rather than `Promise.all` in one step: then, when one pauses, the finished ones
+are not run again on resume.
+
+```ts
+h.loop(l =>
+  l.start()
+   .fork('research')
+   .branch('web', b => b.start()
+     .step('callWeb', {
+       run: async (s, ctx) => ({ web: await callSubAgent(webAgent, `${ctx.sessionId}:web`, {}, ctx) }),
+       route: () => 'done',
+     })
+     .on('done').end())                       // inside a branch, .end() ends the branch
+   .branch('docs', b => b.start()
+     .step('callDocs', {
+       run: async (s, ctx) => ({ docs: await callSubAgent(docsAgent, `${ctx.sessionId}:docs`, {}, ctx) }),
+       route: () => 'done',
+     })
+     .on('done').end())
+   .join('merge', { run: mergeResults, route: () => 'done' })
+   .on('done').end()
+)
+```
+
+If a fork fails fast while a sub agent is paused, that sub agent's own session stays
+paused in its store — clean it up or reuse it the next time the step runs.
+
+### Observers
+
+An `Observer` receives telemetry hooks for a run. Pass it as `observer` in the resources
+of `agent.run()` or `agent.resume()`. Combine several with `composeObservers([a, b])`;
+a hook that throws is reported to `onObserverError` (or `console.error`) and never stops
+the run. Every hook is optional.
+
+| Hook | Fires |
+|---|---|
+| `onRunStart(ctx)` | once when a run starts |
+| `onRunEnd(ctx, { signal, durationMs })` | once when a run settles (`$stopped` for a stop) |
+| `onStepStart(ctx)` | before each step |
+| `onStepEnd(ctx, { durationMs })` | after a step's `run` succeeds, before its `route` |
+| `onStepError(ctx, { error, durationMs })` | when a step's `run` throws |
+| `onInterrupt(ctx, { prompt, interruptId })` | when a step calls `ctx.interrupt()` |
+| `onEvent(ctx, type, payload)` | on `ctx.emit()` and adapter events such as `llm.response` |
+| `onStepSettled(ctx, event)` | once per step, when its outcome and destination are final |
+
+**`onStepSettled`** is the one hook that tells you, for every step, how it ended and
+where the run goes next. It fires exactly once for each `onStepStart`, on every path:
+
+```
+onStepStart → onStepEnd | onStepError | onInterrupt → onStepSettled → onRunEnd
+```
+
+It also fires for a fork node and for each step inside a branch (`ctx.branchPath` names the
+branch). A graph-definition error (`UnknownSignalError`, `NoNextStepError`,
+`MissingReducerError`) settles with `next.kind === 'throw'` before the run rejects. It does
+not fire when a run stops before starting a step, or for a finished branch that a resume
+skips.
+
+| `event` field | Meaning |
+|---|---|
+| `outcome` | `'ok'`, `'error'`, `'interrupt'`, or `'stopped'` (a fork whose branches were stopped) |
+| `durationMs` | from `onStepStart` until the destination is known — includes `route` |
+| `update` | what `run` returned, present only when it was applied to state. The raw object — copy it if you keep it |
+| `signal` | what `route` returned, when it was called |
+| `next` | `{ kind: 'step', name }`, `{ kind: 'end' }`, `{ kind: 'pause' }`, or `{ kind: 'throw' }` |
+| `error` | present when `outcome` is `'error'` |
+| `interrupt` | `{ interruptId, prompt }`, when a plain step paused on an interrupt |
+| `fork` | on a fork node that ended done or paused: `{ branches: [{ name, status, touchedKeys }] }` |
+
+```ts
+const logger: Observer = {
+  onStepSettled(ctx, e) {
+    const next = e.next.kind === 'step' ? `→ ${e.next.name}` : e.next.kind
+    console.log(`${ctx.stepName}: ${e.outcome} ${next}`, e.signal ? `(signal ${e.signal})` : '')
+  },
+}
+
+const h = createHarness()({ total: field({ default: () => 0 }) }).loop(l =>
+  l.start()
+   .step('fetch', { run: async () => ({ total: 3 }) })
+   .step('decide', { route: s => (s.total > 0 ? 'done' : 'empty') })
+   .on('done').end()
+   .on('empty').end()
+)
+
+await createAgent('demo', h, {}).run({}, { observer: logger })
+// fetch: ok → decide
+// decide: ok end (signal done)
+```
+
 ## API
 
 | Export | Description |
@@ -165,10 +316,12 @@ const resumed = agent.resume(response, sessionId, interruptId)
 | `field<T>(opts)` | Declares a state field with a default and optional reduce function. |
 | `required()` | Marks a provider slot as required at `createAgent()`. |
 | `runtime()` | Marks a provider slot as required at `agent.run()`. |
-| `composeObservers(...observers)` | Merges multiple `Observer` instances into one fan-out observer. |
+| `composeObservers([a, b], onObserverError?)` | Merges multiple `Observer` instances into one fan-out observer; a throwing observer is isolated and reported to `onObserverError`. |
 | `SessionStore` | Interface for session persistence backends. |
 | `StoredRun` | Type for a persisted run snapshot. Includes `agentId`, `runId`, `sessionId`, `phase`, and state. |
-| `Observer` | Interface for telemetry hooks on run and step lifecycle events. |
+| `Observer` | Interface for telemetry hooks on run and step lifecycle events (see [Observers](#observers)). |
+| `StepSettledEvent` | Payload of `Observer.onStepSettled` — outcome, duration, update, signal, next, error, interrupt, fork. |
+| `StepSettledNext` | Where the run goes after a step settles: `step`, `end`, `pause`, or `throw`. |
 | `ObserverAware` | Interface for provider objects that accept an `Observer` binding via `bindObserver()`. |
 | `RunContext` | Context passed to run-level observer hooks — `agentId`, `sessionId`. |
 | `StepContext` | Context passed to step-level observer hooks — `agentId`, `sessionId`, `stepName`. |

package/dist/index.d.ts

@@ -145,6 +145,62 @@ interface StepContext {
      */
     readonly branchPath?: readonly string[];
 }
+/**
+ * Where execution goes after a step settles.
+ *
+ * - `step` — the next step to run (a route target, `.next()`, the implicit next step, the
+ *   `l.onError()` fallback, or the join after a fork).
+ * - `end` — the loop ended via `.end()` (inside a fork branch: the branch ended).
+ * - `pause` — the run paused (interrupt, stop, or an unhandled error) and can be continued later.
+ * - `throw` — a graph-definition error (`UnknownSignalError`, `NoNextStepError`,
+ *   `MissingReducerError`) is about to reject the run.
+ */
+type StepSettledNext = {
+    readonly kind: 'step';
+    readonly name: string;
+} | {
+    readonly kind: 'end';
+} | {
+    readonly kind: 'pause';
+} | {
+    readonly kind: 'throw';
+};
+/**
+ * Payload of {@link Observer.onStepSettled}: everything known about one step once its
+ * outcome and destination are final. Optional keys are omitted, never set to `undefined`.
+ */
+interface StepSettledEvent {
+    /** `'stopped'` only occurs on fork nodes whose branches were stopped without an interrupt. */
+    readonly outcome: 'ok' | 'error' | 'interrupt' | 'stopped';
+    /** From `onStepStart` until the destination is known — includes `route()`. */
+    readonly durationMs: number;
+    /**
+     * The value `run()` returned, present iff it was applied to state. The raw reference,
+     * unfiltered — it may be aliased into state, so copy it before the next step if you keep it.
+     */
+    readonly update?: Record<string, unknown>;
+    /** Present iff `route()` was called and returned a signal. */
+    readonly signal?: string;
+    readonly next: StepSettledNext;
+    /** Present iff `outcome` is `'error'`. */
+    readonly error?: Error;
+    /** Present iff `outcome` is `'interrupt'` on a plain (non-fork) step. */
+    readonly interrupt?: {
+        readonly interruptId: string;
+        readonly prompt: unknown;
+    };
+    /**
+     * Fork nodes only, when every branch ended done or paused (not when the fork failed):
+     * each branch in declaration order.
+     */
+    readonly fork?: {
+        readonly branches: readonly {
+            readonly name: string;
+            readonly status: 'done' | 'paused';
+            readonly touchedKeys: readonly string[];
+        }[];
+    };
+}
 /**
  * Observability hook interface.  All methods are optional — implement only
  * the hooks you need.
@@ -193,6 +249,13 @@ interface Observer {
      * by LLM adapters (e.g. `'llm.response'`).
      */
     onEvent?: (ctx: StepContext, type: string, payload: unknown) => void;
+    /**
+     * Called exactly once per step, on every path, once the step's outcome and destination
+     * are final: after `onStepEnd` / `onStepError` / `onInterrupt` (when that hook fires on the
+     * path) and before `onRunEnd`. Also fires for fork nodes and for steps inside fork branches
+     * (with `ctx.branchPath`). Not fired when a run stops before starting a step.
+     */
+    onStepSettled?: (ctx: StepContext, event: StepSettledEvent) => void;
 }
 /**
  * The telemetry a resource needs to attribute an `invoke()` call to the correct
@@ -983,4 +1046,4 @@ declare class LeaseExpiredError extends Error {
     constructor(sessionId: string);
 }
 
-export { type Agent, type BranchCursor, type BranchDef, type ClaimOptions, type Cursor, type DeepWithMarkers, type FieldDefinition, type ForkCursor, type ForkDef, type FrameworkState, type Harness, type Lease, LeaseExpiredError, type LoopDefinition, type LoopNode, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, type ObserverErrorContext, type ObserverErrorSink, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunContext, type RunFn, type RuntimeMarker, SessionBusyError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SignalTransition, type StateFromSchema, type StepContext, type StepDef, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TelemetryContext, type TransitionTarget, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };
+export { type Agent, type BranchCursor, type BranchDef, type ClaimOptions, type Cursor, type DeepWithMarkers, type FieldDefinition, type ForkCursor, type ForkDef, type FrameworkState, type Harness, type Lease, LeaseExpiredError, type LoopDefinition, type LoopNode, LoopNotDefinedError, NoInterruptError, type Observer, type ObserverAware, type ObserverErrorContext, type ObserverErrorSink, REQUIRED_TAG, RUNTIME_TAG, type RequiredMarker, type RouteFn, type RunContext, type RunFn, type RuntimeMarker, SessionBusyError, SessionInFlightError, SessionPendingInterruptError, type SessionStore, type SignalTransition, type StateFromSchema, type StepContext, type StepDef, type StepSettledEvent, type StepSettledNext, type StepState, StoreLoadError, type StoredRun, type StoredRunMetadata, type TelemetryContext, type TransitionTarget, composeObservers, createAgent, createHarness, field, isForkCursor, isForkDef, isRequiredMarker, isRuntimeMarker, required, runtime };

package/dist/index.js

@@ -532,6 +532,9 @@ function composeObservers(observers, onObserverError) {
     },
     onEvent: (ctx, type, payload) => {
       for (const o of observers) safeInvoke("onEvent", () => o.onEvent?.(ctx, type, payload), onObserverError);
+    },
+    onStepSettled: (ctx, event) => {
+      for (const o of observers) safeInvoke("onStepSettled", () => o.onStepSettled?.(ctx, event), onObserverError);
     }
   };
 }
@@ -645,6 +648,15 @@ function applyUpdate(state, update, schema, touchedKeys) {
     touchedKeys?.add(key);
   }
 }
+function fireSettled(obs, stepCtx, stepStart, fields, onObserverError) {
+  const hook = obs?.onStepSettled;
+  if (hook === void 0) return;
+  const event = { ...fields, durationMs: Date.now() - stepStart };
+  safeInvoke("onStepSettled", () => hook(stepCtx, event), onObserverError);
+}
+function asError(e) {
+  return e instanceof Error ? e : new Error(String(e));
+}
 async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callbacks) {
   const { onBeforeStep, onAfterStep, onError, onComplete, onInterrupt } = callbacks ?? {};
   const obs = callbacks?.observer;
@@ -742,6 +754,8 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
       }
     }
     let runSucceeded = false;
+    let applied;
+    const settle = (fields) => fireSettled(obs, stepCtx, stepStart, { ...fields, ...applied !== void 0 ? { update: applied } : {} }, onObserverError);
     if (step.run !== void 0) {
       const hadResponses = Object.keys(state.$interruptResponses).length > 0;
       try {
@@ -750,6 +764,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
           ctx
         );
         applyUpdate(state, update, schema, callbacks?.touchedKeys);
+        applied = update;
         if (hadResponses) {
           state.$interrupt = null;
           state.$interruptResponses = {};
@@ -759,6 +774,7 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
         if (isInterruptPause(e)) {
           onInterrupt?.(e.prompt, e.interruptId);
           safeInvoke("onInterrupt", () => obs?.onInterrupt?.(stepCtx, { prompt: e.prompt, interruptId: e.interruptId }), onObserverError);
+          settle({ outcome: "interrupt", interrupt: { interruptId: e.interruptId, prompt: e.prompt }, next: { kind: "pause" } });
           safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$interrupt", durationMs: Date.now() - runStart }), onObserverError);
           return { state, signal: "$interrupt", cursor, paused: true };
         }
@@ -780,31 +796,42 @@ async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callb
         signal = routeFn(state);
       } catch (e) {
         state.$error = e instanceof Error ? e : new Error(String(e));
+        settle({ outcome: "error", error: state.$error, next: { kind: "pause" } });
         safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$error", durationMs: Date.now() - runStart }), onObserverError);
         return { state, signal: "$error", cursor, paused: true };
       }
+      const routed = runSucceeded || step.run === void 0 ? { outcome: "ok", signal } : { outcome: "error", signal, error: state.$error };
       const transition = step.transitions.find((t) => t.signal === signal);
       if (transition === void 0) {
-        throw new UnknownSignalError(cursor, signal);
+        const unknownSignal = new UnknownSignalError(cursor, signal);
+        settle({ outcome: "error", signal, error: unknownSignal, next: { kind: "throw" } });
+        throw unknownSignal;
       }
       if (transition.target.kind === "end") {
+        settle({ ...routed, next: { kind: "end" } });
         onComplete?.(state, signal);
         safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal, durationMs: Date.now() - runStart }), onObserverError);
         return { state, signal, cursor: null, paused: false };
       }
+      settle({ ...routed, next: { kind: "step", name: transition.target.name } });
       cursor = transition.target.name;
     } else if (step.run !== void 0 && !runSucceeded) {
       if (graph.onError !== void 0) {
+        settle({ outcome: "error", error: state.$error, next: { kind: "step", name: graph.onError } });
         cursor = graph.onError;
       } else {
+        settle({ outcome: "error", error: state.$error, next: { kind: "pause" } });
         safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$error", durationMs: Date.now() - runStart }), onObserverError);
         return { state, signal: "$error", cursor, paused: true };
       }
     } else {
       const next = step.next ?? implicitNextMap.get(cursor) ?? null;
       if (next === null) {
-        throw new NoNextStepError(cursor);
+        const noNext = new NoNextStepError(cursor);
+        settle({ outcome: "error", error: noNext, next: { kind: "throw" } });
+        throw noNext;
       }
+      settle({ outcome: "ok", next: { kind: "step", name: next } });
       cursor = next;
     }
   }
@@ -842,16 +869,25 @@ async function dispatchFork(forkNode, priorBranches, outerState, outerCtx, schem
   );
   const { onBeforeStep: _outerOnBeforeStep, onAfterStep: _outerOnAfterStep, onComplete: _outerOnComplete, ...branchCallbacksRest } = callbacks ?? {};
   const branchCallbacksBase = callbacks !== void 0 ? branchCallbacksRest : void 0;
-  const outcomes = await Promise.all(
+  const settled = await Promise.allSettled(
     forkNode.branches.map(async (branch, i) => {
       const prior = priorByName.get(branch.name);
-      const outcome = await runBranch(branch, prior, outerState, outerCtx, schema, shouldStop, branchSignals[i], branchCallbacksBase);
+      let outcome;
+      try {
+        outcome = await runBranch(branch, prior, outerState, outerCtx, schema, shouldStop, branchSignals[i], branchCallbacksBase);
+      } catch (e) {
+        for (const controller of localAborts) controller.abort();
+        throw e;
+      }
       if (outcome.result.paused && outcome.result.signal === "$error") {
         for (const controller of localAborts) controller.abort();
       }
       return outcome;
     })
   );
+  const rejected = settled.find((r) => r.status === "rejected");
+  if (rejected !== void 0) throw rejected.reason;
+  const outcomes = settled.map((r) => r.value);
   const failed = outcomes.find((o) => o.result.paused && o.result.signal === "$error");
   if (failed !== void 0) {
     return { kind: "failed", error: failed.result.state.$error };
@@ -875,7 +911,8 @@ async function dispatchFork(forkNode, priorBranches, outerState, outerCtx, schem
         touchedKeys: [...o.touchedKeys]
       };
     });
-    return { kind: "paused", forkCursor: { kind: "fork", fork: forkNode.name, branches } };
+    const interrupted = outcomes.some((o) => o.result.paused && o.result.signal === "$interrupt");
+    return { kind: "paused", forkCursor: { kind: "fork", fork: forkNode.name, branches }, interrupted };
   }
   const keyOwners = /* @__PURE__ */ new Map();
   for (const outcome of outcomes) {
@@ -899,7 +936,10 @@ async function dispatchFork(forkNode, priorBranches, outerState, outerCtx, schem
       }
     }
   }
-  return { kind: "success" };
+  return {
+    kind: "success",
+    branches: outcomes.map((o) => ({ name: o.name, status: "done", touchedKeys: [...o.touchedKeys] }))
+  };
 }
 async function handleFork(forkNode, priorBranches, state, ctx, schema, shouldStop, callbacks, obs, runCtx, runStart, implicitNextMap, graph) {
   const stepCtx = {
@@ -911,18 +951,35 @@ async function handleFork(forkNode, priorBranches, state, ctx, schema, shouldSto
   const stepStart = Date.now();
   const onObserverError = callbacks?.onObserverError;
   safeInvoke("onStepStart", () => obs?.onStepStart?.(stepCtx), onObserverError);
-  const dispatch = await dispatchFork(forkNode, priorBranches, state, ctx, schema, shouldStop, callbacks);
+  let dispatch;
+  try {
+    dispatch = await dispatchFork(forkNode, priorBranches, state, ctx, schema, shouldStop, callbacks);
+  } catch (e) {
+    fireSettled(obs, stepCtx, stepStart, { outcome: "error", error: asError(e), next: { kind: "throw" } }, onObserverError);
+    throw e;
+  }
   if (dispatch.kind === "paused") {
-    safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$interrupt", durationMs: Date.now() - runStart }), onObserverError);
-    return { done: true, result: { state, signal: "$interrupt", cursor: dispatch.forkCursor, paused: true } };
+    const fork = {
+      branches: dispatch.forkCursor.branches.map((b) => ({ name: b.name, status: b.status, touchedKeys: b.touchedKeys }))
+    };
+    if (dispatch.interrupted === true) {
+      fireSettled(obs, stepCtx, stepStart, { outcome: "interrupt", next: { kind: "pause" }, fork }, onObserverError);
+      safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$interrupt", durationMs: Date.now() - runStart }), onObserverError);
+      return { done: true, result: { state, signal: "$interrupt", cursor: dispatch.forkCursor, paused: true } };
+    }
+    fireSettled(obs, stepCtx, stepStart, { outcome: "stopped", next: { kind: "pause" }, fork }, onObserverError);
+    safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$stopped", durationMs: Date.now() - runStart }), onObserverError);
+    return { done: true, result: { state, signal: null, cursor: dispatch.forkCursor, paused: true } };
   }
   if (dispatch.kind === "failed") {
     state.$error = dispatch.error;
     callbacks?.onError?.(state.$error, forkNode.name);
     safeInvoke("onStepError", () => obs?.onStepError?.(stepCtx, { error: state.$error, durationMs: Date.now() - stepStart }), onObserverError);
     if (graph.onError !== void 0) {
+      fireSettled(obs, stepCtx, stepStart, { outcome: "error", error: state.$error, next: { kind: "step", name: graph.onError } }, onObserverError);
       return { done: false, nextCursor: graph.onError };
     }
+    fireSettled(obs, stepCtx, stepStart, { outcome: "error", error: state.$error, next: { kind: "pause" } }, onObserverError);
     safeInvoke("onRunEnd", () => obs?.onRunEnd?.(runCtx, { signal: "$error", durationMs: Date.now() - runStart }), onObserverError);
     return { done: true, result: { state, signal: "$error", cursor: forkNode.name, paused: true } };
   }
@@ -931,8 +988,11 @@ async function handleFork(forkNode, priorBranches, state, ctx, schema, shouldSto
   callbacks?.onAfterStep?.(forkNode.name, state);
   const next = forkNode.next ?? implicitNextMap.get(forkNode.name) ?? null;
   if (next === null) {
-    throw new NoNextStepError(forkNode.name);
+    const noNext = new NoNextStepError(forkNode.name);
+    fireSettled(obs, stepCtx, stepStart, { outcome: "error", error: noNext, next: { kind: "throw" } }, onObserverError);
+    throw noNext;
   }
+  fireSettled(obs, stepCtx, stepStart, { outcome: "ok", next: { kind: "step", name: next }, fork: { branches: dispatch.branches } }, onObserverError);
   return { done: false, nextCursor: next };
 }