@xdelivered/emberflow 0.2.0 → 0.4.0

package/server/runRegistry.ts

@@ -5,11 +5,13 @@ import type {
 import { InMemoryTraceSink, startRun, type FlowRun, type NodeRegistry } from '../src/engine';
 import { createDefaultRegistry } from '../src/nodes';
 import { redactSecrets } from './redact';
-import { makeSubflowRunner } from './subflowRunner';
+import { makeSubflowRunner, type DrillEntry, type DrillState } from './subflowRunner';
 
 /** SSE-shaped events, mirroring ExecutorEvents 1:1. */
 export type RunEvent =
-  | { type: 'nodeState'; nodeId: string; state: NodeRunState }
+  /** `workflowId` is the flow the node belongs to: the root flow for the
+   *  run's own nodes, the CHILD flow's id for a stepped subflow's nodes. */
+  | { type: 'nodeState'; workflowId: string; nodeId: string; state: NodeRunState }
   | { type: 'log'; line: LogLine }
   | {
       type: 'finished';
@@ -27,6 +29,25 @@ interface LiveRun {
   listeners: Set<Listener>;
   finished: boolean;
   cleanupTimer?: ReturnType<typeof setTimeout>;
+  /** Serializes step() calls per run: a second concurrent step() would
+   *  re-arm `state.onChildStarted` (last writer wins) and double-drive the
+   *  executor, hanging the first caller. */
+  stepChain?: Promise<unknown>;
+  /** Present only for stepped runs: subflow drill-in state (see step()). */
+  drill?: {
+    state: DrillState;
+    /** The ROOT executor's step() promise left pending while a child runs. */
+    rootPendingStep?: Promise<boolean>;
+  };
+}
+
+/** Result of one composite step on a stepped run (see RunRegistry.step). */
+export interface StepResult {
+  done: boolean;
+  /** Set when this step drove execution INTO a subflow child. */
+  entered?: { workflowId: string; nodeId: string };
+  /** Set when this step completed the deepest child and popped back out. */
+  exited?: true;
 }
 
 const RETAIN_FINISHED_MS = 10 * 60 * 1000; // 10 minutes
@@ -93,6 +114,10 @@ export class RunRegistry {
        *  error-handler run — stamped onto this run's `finished` event as
        *  `errorHandler: { firedBy }`. Only meaningful alongside isErrorHandler. */
       errorHandlerFiredBy?: string;
+      /** When true (a step-mode run), Subflow children become step-drivable:
+       *  entering one pauses inside it instead of running it to completion in
+       *  a single opaque step. Drive the run via `step(runId)`. */
+      stepped?: boolean;
     },
   ): { runId: string; handle: FlowRun } {
     this.evictIfNeeded();
@@ -116,6 +141,11 @@ export class RunRegistry {
     // the child via loadFlow, runs it to completion on the same registry
     // sharing the parent's environment, and forwards its (prefixed) logs into
     // this run's SSE stream via `onLog`.
+    // Stepped runs share ONE drill state across the root's runner and every
+    // nested child's runner (makeSubflowRunner threads `opts` through), so a
+    // grandchild pushes onto the same stack and nesting works.
+    const drillState: DrillState | undefined = opts.stepped ? { stack: [] } : undefined;
+
     const subflowRunner = makeSubflowRunner(
       {
         loadFlow: (id) => this.loadFlow?.(id),
@@ -127,6 +157,18 @@ export class RunRegistry {
         mockRun: opts.mockRun,
         trace: this.sink,
         onLog: (line) => emit({ type: 'log', line }),
+        drill: drillState,
+        // Stepped children stream node states into this run's SSE stream,
+        // tagged with the CHILD flow's id so the client can route them.
+        // After a drill-aware cancel the rejected parent executions unwind in
+        // the background (recording their Subflow nodes as failed) — child
+        // states from that unwinding must not reach subscribers post-finish.
+        onNodeState: drillState
+          ? (workflowId, nodeId, state) => {
+              if (drillState.cancelled) return;
+              emit({ type: 'nodeState', workflowId, nodeId, state });
+            }
+          : undefined,
       },
       [flow.id],
     );
@@ -145,9 +187,14 @@ export class RunRegistry {
       trace: this.sink,
       subflowRunner,
       events: {
-        onNodeStateChange: (nodeId, state) => emit({ type: 'nodeState', nodeId, state }),
+        onNodeStateChange: (nodeId, state) =>
+          emit({ type: 'nodeState', workflowId: flow.id, nodeId, state }),
         onLog: (line) => emit({ type: 'log', line }),
         onRunFinished: (run) => {
+          // Idempotent: after a drill-aware cancel the root executor's pending
+          // Subflow execution can fail in the background and re-finish the run
+          // — subscribers already saw the cancelled `finished` event.
+          if (entry.finished) return;
           emit({
             type: 'finished',
             run,
@@ -163,10 +210,160 @@ export class RunRegistry {
     });
 
     entry.handle = handle;
+    if (drillState) entry.drill = { state: drillState };
     this.runs.set(handle.run.id, entry);
     return { runId: handle.run.id, handle };
   }
 
+  /**
+   * One composite step of a run, drill-aware. For stepped runs a Subflow node
+   * is no longer one opaque step: entering it pauses inside the child
+   * (`entered`), subsequent steps drive the child's nodes, and completing the
+   * child pops back out (`exited`). Non-stepped runs (no drill state) fall
+   * back to a plain executor step. Unknown run → undefined.
+   */
+  async step(runId: string): Promise<StepResult | undefined> {
+    const entry = this.runs.get(runId);
+    if (!entry) return undefined;
+    // Serialize per run: concurrent step() calls would each arm
+    // `state.onChildStarted` (last writer wins) and double-drive the
+    // executor, so the second caller waits for the first to settle.
+    const result = (entry.stepChain ?? Promise.resolve()).then(() => this.stepLevels(entry));
+    entry.stepChain = result.catch(() => undefined);
+    return result;
+  }
+
+  /**
+   * One composite step, drill-aware. Structured as a loop over levels: each
+   * pass drives the current deepest level (a pending stashed step, or a fresh
+   * executor step) while racing "a new child started". Popping a finished
+   * child continues the loop on its parent's stashed step WITH the race still
+   * armed — the parent's still-pending Subflow node execution may call
+   * runSubflow again (retry, or a custom node making sequential calls), and
+   * that re-entry must surface as `entered`, not deadlock the fold.
+   */
+  private async stepLevels(entry: LiveRun): Promise<StepResult> {
+    const drill = entry.drill;
+    if (!drill) {
+      const more = await entry.handle.step();
+      return { done: !more };
+    }
+
+    const { state } = drill;
+    // Cancelled mid-drill: the stack was already unwound by cancel(); report
+    // done without driving anything.
+    if (state.cancelled) return { done: true };
+
+    // Set once this step pops a child; carried onto whatever this step
+    // ultimately reports (including an `entered` for a re-run child).
+    let exited = false;
+    const withExit = (r: StepResult): StepResult => (exited ? { ...r, exited: true } : r);
+
+    for (;;) {
+      // The level being stepped: the deepest drilled-in child, or the root run.
+      const level = state.stack.length > 0 ? state.stack[state.stack.length - 1] : undefined;
+      const handle = level ? level.handle : entry.handle;
+      const pendingStep = level ? level.pendingStep : drill.rootPendingStep;
+      const setPending = (p: Promise<boolean> | undefined): void => {
+        if (level) level.pendingStep = p;
+        else drill.rootPendingStep = p;
+      };
+
+      // A Subflow node's execution blocks inside runSubflow until its child
+      // completes, so the step promise alone can never report "entered a
+      // child" — arm the child-started signal BEFORE awaiting and race them.
+      const childStarted = new Promise<DrillEntry>((res) => {
+        state.onChildStarted = res;
+      });
+      const stepPromise = pendingStep ?? handle.step();
+      setPending(undefined);
+
+      type Raced = { kind: 'stepped'; more: boolean } | { kind: 'entered'; child: DrillEntry };
+      let raced: Raced;
+      try {
+        raced = await Promise.race([
+          stepPromise.then((more): Raced => ({ kind: 'stepped', more })),
+          childStarted.then((child): Raced => ({ kind: 'entered', child })),
+        ]);
+      } catch (err) {
+        state.onChildStarted = undefined;
+        if (!level) throw err;
+        // A child level's step threw outright (not a recorded node failure —
+        // the executor catches those). Reject the parent's blocked runSubflow,
+        // which surfaces it as the Subflow node's error, then fold the parent
+        // (next loop pass, race re-armed).
+        state.stack.pop();
+        level.reject(err);
+        exited = true;
+        continue;
+      }
+      state.onChildStarted = undefined;
+
+      if (raced.kind === 'entered') {
+        // The level's step stays pending for the whole child run — stash it;
+        // the step that later pops this child folds its boolean back in.
+        setPending(stepPromise);
+        return withExit({
+          done: false,
+          entered: { workflowId: raced.child.workflowId, nodeId: raced.child.viaNodeId },
+        });
+      }
+
+      if (raced.more) return withExit({ done: false });
+
+      // This level has no more nodes: its run is complete.
+      if (!level) return withExit({ done: true });
+
+      // Pop the finished child and hand its completed run (succeeded OR failed)
+      // to the parent's blocked runSubflow — the success/failure semantics live
+      // in subflowRunner, byte-identical to the non-stepped path. The parent's
+      // stashed step is folded in by the next loop pass, with the child-started
+      // race re-armed so a retrying Subflow node re-entering its child yields
+      // `exited` + `entered` instead of hanging.
+      state.stack.pop();
+      level.resolve(level.handle.run);
+      exited = true;
+    }
+  }
+
+  /**
+   * Cancel a run, drill-aware. For a stepped run drilled into subflows this
+   * cancels every stacked child deepest-first and rejects the promise each
+   * parent's Subflow node execution is blocked on — those pending executions
+   * then unwind in the background exactly like an in-flight node after a
+   * plain root cancel today (recorded, but the run is already finished).
+   * step() after cancel reports { done: true } without executing anything.
+   * Returns false for an unknown run.
+   */
+  /** Cancels every live (non-finished) run — the server's shutdown path, so
+   *  in-flight executions (and their drilled subflow children) don't keep
+   *  running headless after the process is asked to die. */
+  shutdown(): void {
+    for (const [id, run] of this.runs) {
+      if (!run.finished) this.cancel(id);
+    }
+  }
+
+  cancel(runId: string): boolean {
+    const entry = this.runs.get(runId);
+    if (!entry) return false;
+    const drill = entry.drill;
+    if (drill) {
+      const { state } = drill;
+      state.cancelled = true;
+      state.onChildStarted = undefined;
+      while (state.stack.length > 0) {
+        const child = state.stack.pop()!;
+        child.pendingStep = undefined;
+        child.handle.cancel();
+        child.reject(new Error('run cancelled'));
+      }
+      drill.rootPendingStep = undefined;
+    }
+    entry.handle.cancel();
+    return true;
+  }
+
   /**
    * Best-effort: fires `errorOperation` (resolved via the same `loadFlow`
    * callback Subflow nodes use) as a new run when `failedRun` finished with

package/server/setupStatus.test.ts

@@ -78,6 +78,9 @@ describe('GET /setup-status', () => {
     const body = await res.json();
 
     expect(Array.isArray(body.agents)).toBe(true);
+    // The temp project dir isn't inside a git repo — reported as such so the
+    // checklist can gate the agent features on it.
+    expect(body.git).toEqual({ repo: false });
     // A fresh project has no environments file → the synthesized fallback is
     // reported as unconfigured with zero real environments.
     expect(body.environments).toMatchObject({

package/server/stepDrill.test.ts

@@ -0,0 +1,380 @@
+import { describe, expect, it } from 'vitest';
+import type { WorkflowDefinition, WorkflowNode } from '../src/engine';
+import { createDefaultRegistry } from '../src/nodes';
+import { RunRegistry, type RunEvent, type StepResult } from './runRegistry';
+
+const base = { version: 1, createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z' };
+
+const runOpts = { secrets: {}, vars: {}, environment: 'test', safeMode: false };
+
+function node(id: string, type: string, extra: Partial<WorkflowNode> = {}): WorkflowNode {
+  return { id, type, label: extra.label ?? id, position: { x: 0, y: 0 }, config: {}, ...extra };
+}
+
+function flowStore(flows: WorkflowDefinition[]) {
+  const byId = new Map(flows.map((f) => [f.id, f]));
+  return (id: string) => byId.get(id);
+}
+
+/** Default registry (no artificial node delays) + deterministic test nodes. */
+function registry() {
+  const r = createDefaultRegistry(0);
+  r.register(
+    { type: 'double', label: 'Double', inputSchema: { fields: [{ name: 'value', type: 'number' }] } },
+    async (ctx) => ({ value: Number(ctx.input.value) * 2 }),
+  );
+  r.register({ type: 'boom', label: 'Boom' }, async () => {
+    throw new Error('kaboom');
+  });
+  return r;
+}
+
+/** Input → Double → Result. */
+const childFlow: WorkflowDefinition = {
+  ...base,
+  id: 'child-flow',
+  name: 'Child Flow',
+  nodes: [
+    node('cin', 'Input', { config: { fields: [], defaults: {} } }),
+    node('cdouble', 'double', { inputMap: { value: { sourceNodeId: 'cin', sourceField: 'value' } } }),
+    node('cres', 'Result', { inputMap: { data: { sourceNodeId: 'cdouble', sourceField: '$' } } }),
+  ],
+  edges: [
+    { id: 'e1', source: 'cin', target: 'cdouble' },
+    { id: 'e2', source: 'cdouble', target: 'cres' },
+  ],
+};
+
+/** Input → Subflow(child) → Result. */
+const parentFlow: WorkflowDefinition = {
+  ...base,
+  id: 'parent-flow',
+  name: 'Parent Flow',
+  nodes: [
+    node('pin', 'Input', { config: { fields: [], defaults: {} } }),
+    node('sub', 'Subflow', {
+      config: { workflowId: 'child-flow' },
+      inputMap: { value: { sourceNodeId: 'pin', sourceField: 'value' } },
+    }),
+    node('pres', 'Result', { inputMap: { data: { sourceNodeId: 'sub', sourceField: '$' } } }),
+  ],
+  edges: [
+    { id: 'e1', source: 'pin', target: 'sub' },
+    { id: 'e2', source: 'sub', target: 'pres' },
+  ],
+};
+
+/** Drives a stepped run to completion, returning every StepResult in order. */
+async function stepToEnd(runs: RunRegistry, runId: string): Promise<StepResult[]> {
+  const seq: StepResult[] = [];
+  for (let i = 0; i < 50; i += 1) {
+    const result = await runs.step(runId);
+    expect(result).toBeDefined();
+    seq.push(result!);
+    if (result!.done) return seq;
+  }
+  throw new Error('run did not finish within 50 steps');
+}
+
+describe('subflow step drill-in', () => {
+  it('steps into and out of a child: entered marker, child steps, exited marker, same output as non-stepped', async () => {
+    const runs = new RunRegistry(flowStore([parentFlow, childFlow]), registry());
+    const { runId, handle } = runs.create(parentFlow, { ...runOpts, input: { value: 3 }, stepped: true });
+
+    const events: RunEvent[] = [];
+    runs.subscribe(runId, (e) => events.push(e));
+
+    const seq = await stepToEnd(runs, runId);
+
+    // pin → entered(sub) → cin → cdouble → cres(exits) → pres(done)
+    expect(seq).toEqual([
+      { done: false },
+      { done: false, entered: { workflowId: 'child-flow', nodeId: 'sub' } },
+      { done: false },
+      { done: false },
+      { done: false, exited: true },
+      { done: true },
+    ]);
+    expect(handle.run.status).toBe('succeeded');
+
+    // Child node states streamed into the ROOT run's event stream, tagged
+    // with the child flow's id; parent states carry the parent flow's id.
+    const stateIds = events
+      .filter((e) => e.type === 'nodeState')
+      .map((e) => (e.type === 'nodeState' ? `${e.workflowId}:${e.nodeId}` : ''));
+    expect(stateIds).toContain('child-flow:cdouble');
+    expect(stateIds).toContain('parent-flow:sub');
+    expect(stateIds).not.toContain('parent-flow:cdouble');
+
+    // Output identical to a non-stepped run of the same flow.
+    const plain = runs.create(parentFlow, { ...runOpts, input: { value: 3 } });
+    await plain.handle.runToEnd();
+    expect(plain.handle.run.status).toBe('succeeded');
+    expect(handle.run.nodeStates.pres.output).toEqual(plain.handle.run.nodeStates.pres.output);
+    expect(handle.run.nodeStates.pres.output).toEqual({ data: { data: { value: 6 } } });
+  });
+
+  it('reports done on the exit step when the Subflow is the parent’s last node (pending-step fold)', async () => {
+    const tailFlow: WorkflowDefinition = {
+      ...base,
+      id: 'tail-flow',
+      name: 'Tail Flow',
+      nodes: [
+        node('pin', 'Input', { config: { fields: [], defaults: {} } }),
+        node('sub', 'Subflow', {
+          config: { workflowId: 'child-flow' },
+          inputMap: { value: { sourceNodeId: 'pin', sourceField: 'value' } },
+        }),
+      ],
+      edges: [{ id: 'e1', source: 'pin', target: 'sub' }],
+    };
+    const runs = new RunRegistry(flowStore([tailFlow, childFlow]), registry());
+    const { runId, handle } = runs.create(tailFlow, { ...runOpts, input: { value: 2 }, stepped: true });
+
+    const seq = await stepToEnd(runs, runId);
+    // The step that pops the child must fold the parent's pending step()
+    // boolean in: the run is over, so done arrives WITH the exit, not late.
+    expect(seq[seq.length - 1]).toEqual({ done: true, exited: true });
+    expect(handle.run.status).toBe('succeeded');
+    expect(handle.run.nodeStates.sub.output).toEqual({ data: { value: 4 } });
+  });
+
+  it('nests: child-in-child yields entered/entered/exited/exited ordering', async () => {
+    const midFlow: WorkflowDefinition = {
+      ...base,
+      id: 'mid-flow',
+      name: 'Mid Flow',
+      nodes: [
+        node('min', 'Input', { config: { fields: [], defaults: {} } }),
+        node('msub', 'Subflow', {
+          config: { workflowId: 'child-flow' },
+          inputMap: { value: { sourceNodeId: 'min', sourceField: 'value' } },
+        }),
+        node('mres', 'Result', { inputMap: { data: { sourceNodeId: 'msub', sourceField: '$' } } }),
+      ],
+      edges: [
+        { id: 'e1', source: 'min', target: 'msub' },
+        { id: 'e2', source: 'msub', target: 'mres' },
+      ],
+    };
+    const topFlow: WorkflowDefinition = {
+      ...base,
+      id: 'top-flow',
+      name: 'Top Flow',
+      nodes: [
+        node('tin', 'Input', { config: { fields: [], defaults: {} } }),
+        node('tsub', 'Subflow', {
+          config: { workflowId: 'mid-flow' },
+          inputMap: { value: { sourceNodeId: 'tin', sourceField: 'value' } },
+        }),
+        node('tres', 'Result', { inputMap: { data: { sourceNodeId: 'tsub', sourceField: '$' } } }),
+      ],
+      edges: [
+        { id: 'e1', source: 'tin', target: 'tsub' },
+        { id: 'e2', source: 'tsub', target: 'tres' },
+      ],
+    };
+
+    const runs = new RunRegistry(flowStore([topFlow, midFlow, childFlow]), registry());
+    const { runId, handle } = runs.create(topFlow, { ...runOpts, input: { value: 1 }, stepped: true });
+
+    const seq = await stepToEnd(runs, runId);
+    const markers = seq
+      .filter((s) => s.entered || s.exited)
+      .map((s) => (s.entered ? { entered: s.entered } : { exited: true }));
+    expect(markers).toEqual([
+      { entered: { workflowId: 'mid-flow', nodeId: 'tsub' } },
+      { entered: { workflowId: 'child-flow', nodeId: 'msub' } },
+      { exited: true },
+      { exited: true },
+    ]);
+    expect(handle.run.status).toBe('succeeded');
+    expect(handle.run.nodeStates.tres.output).toEqual({ data: { data: { data: { value: 2 } } } });
+  });
+
+  it('a child failure mid-step fails the parent Subflow node with the child’s error, identically to non-stepped', async () => {
+    const boomChild: WorkflowDefinition = {
+      ...base,
+      id: 'child-flow',
+      name: 'Child Boom',
+      nodes: [
+        node('cin', 'Input', { config: { fields: [], defaults: {} } }),
+        node('cboom', 'boom'),
+      ],
+      edges: [{ id: 'e1', source: 'cin', target: 'cboom' }],
+    };
+    const runs = new RunRegistry(flowStore([parentFlow, boomChild]), registry());
+    const { runId, handle } = runs.create(parentFlow, { ...runOpts, input: { value: 3 }, stepped: true });
+
+    const seq = await stepToEnd(runs, runId);
+    // pin → entered → cin → cboom (child fails; exit folds the parent's
+    // failure in, so done arrives with the exit)
+    expect(seq[1]).toEqual({ done: false, entered: { workflowId: 'child-flow', nodeId: 'sub' } });
+    expect(seq[seq.length - 1]).toEqual({ done: true, exited: true });
+    expect(handle.run.status).toBe('failed');
+    expect(handle.run.nodeStates.sub.status).toBe('failed');
+    expect(handle.run.nodeStates.pres.status).toBe('skipped');
+
+    // Same error text as a non-stepped run of the same flows.
+    const plain = runs.create(parentFlow, { ...runOpts, input: { value: 3 } });
+    await plain.handle.runToEnd();
+    expect(plain.handle.run.status).toBe('failed');
+    expect(handle.run.nodeStates.sub.error).toBe(plain.handle.run.nodeStates.sub.error);
+    expect(handle.run.nodeStates.sub.error).toBe('subflow "Child Boom" failed: kaboom');
+  });
+
+  it('a Subflow node with retry re-enters the child after a failed attempt (exited+entered), without hanging', async () => {
+    // Child whose work node fails on the FIRST execution only.
+    let flakyCalls = 0;
+    const r = registry();
+    r.register({ type: 'flaky', label: 'Flaky' }, async () => {
+      flakyCalls += 1;
+      if (flakyCalls === 1) throw new Error('first try fails');
+      return { ok: true };
+    });
+    const flakyChild: WorkflowDefinition = {
+      ...base,
+      id: 'child-flow',
+      name: 'Flaky Child',
+      nodes: [
+        node('cin', 'Input', { config: { fields: [], defaults: {} } }),
+        node('cflaky', 'flaky'),
+      ],
+      edges: [{ id: 'e1', source: 'cin', target: 'cflaky' }],
+    };
+    const retryParent: WorkflowDefinition = {
+      ...parentFlow,
+      nodes: parentFlow.nodes.map((n) =>
+        n.id === 'sub' ? { ...n, retry: { maxTries: 2, waitMs: 0 } } : n,
+      ),
+    };
+    const runs = new RunRegistry(flowStore([retryParent, flakyChild]), r);
+    const { runId, handle } = runs.create(retryParent, { ...runOpts, input: { value: 3 }, stepped: true });
+
+    const seq = await stepToEnd(runs, runId);
+    // pin → entered → cin → cflaky fails (child run failed; the retrying
+    // Subflow node immediately re-runs the child: exited + entered in ONE
+    // step) → cin → cflaky succeeds (exited) → pres → done.
+    expect(seq).toEqual([
+      { done: false },
+      { done: false, entered: { workflowId: 'child-flow', nodeId: 'sub' } },
+      { done: false },
+      { done: false, exited: true, entered: { workflowId: 'child-flow', nodeId: 'sub' } },
+      { done: false },
+      { done: false, exited: true },
+      { done: true },
+    ]);
+    expect(flakyCalls).toBe(2);
+    expect(handle.run.status).toBe('succeeded');
+    expect(handle.run.nodeStates.sub.status).toBe('succeeded');
+    expect(handle.run.nodeStates.sub.attempts).toBe(2);
+  });
+
+  it('a node making two sequential ctx.runSubflow calls drills both children in turn', async () => {
+    const r = registry();
+    r.register({ type: 'twice', label: 'Twice' }, async (ctx) => {
+      const a = await ctx.runSubflow!('child-flow', { value: 1 });
+      const b = await ctx.runSubflow!('child-flow', { value: 10 });
+      if (a.status === 'failed' || b.status === 'failed') throw new Error('subflow failed');
+      return { a: a.output, b: b.output };
+    });
+    const twiceParent: WorkflowDefinition = {
+      ...base,
+      id: 'twice-flow',
+      name: 'Twice Flow',
+      nodes: [
+        node('pin', 'Input', { config: { fields: [], defaults: {} } }),
+        node('tw', 'twice'),
+      ],
+      edges: [{ id: 'e1', source: 'pin', target: 'tw' }],
+    };
+    const runs = new RunRegistry(flowStore([twiceParent, childFlow]), r);
+    const { runId, handle } = runs.create(twiceParent, { ...runOpts, input: {}, stepped: true });
+
+    const seq = await stepToEnd(runs, runId);
+    const markers = seq
+      .filter((s) => s.entered || s.exited)
+      .map((s) => ({ ...(s.entered ? { entered: s.entered.nodeId } : {}), ...(s.exited ? { exited: true } : {}) }));
+    // First child completes and the SAME step enters the second child.
+    expect(markers).toEqual([
+      { entered: 'tw' },
+      { exited: true, entered: 'tw' },
+      { exited: true },
+    ]);
+    expect(handle.run.status).toBe('succeeded');
+    expect(handle.run.nodeStates.tw.output).toEqual({
+      a: { data: { value: 2 } },
+      b: { data: { value: 20 } },
+    });
+  });
+
+  it('cancel mid-drill cancels the stacked child; later steps report done and no child nodeState follows finished', async () => {
+    const runs = new RunRegistry(flowStore([parentFlow, childFlow]), registry());
+    const { runId, handle } = runs.create(parentFlow, { ...runOpts, input: { value: 3 }, stepped: true });
+
+    const events: RunEvent[] = [];
+    runs.subscribe(runId, (e) => events.push(e));
+
+    // pin → entered(sub) → cin: cancelled while drilled into the child.
+    expect(await runs.step(runId)).toEqual({ done: false });
+    expect(await runs.step(runId)).toEqual({
+      done: false,
+      entered: { workflowId: 'child-flow', nodeId: 'sub' },
+    });
+    expect(await runs.step(runId)).toEqual({ done: false });
+
+    expect(runs.cancel(runId)).toBe(true);
+    expect(handle.run.status).toBe('cancelled');
+
+    // Stepping after cancel executes nothing and reports done.
+    expect(await runs.step(runId)).toEqual({ done: true });
+    expect(await runs.step(runId)).toEqual({ done: true });
+
+    // Let the rejected parent execution unwind in the background, then check
+    // nothing leaked past `finished`: exactly one finished event (status
+    // cancelled) and zero child nodeState events after it.
+    await new Promise((r) => setTimeout(r, 0));
+    await new Promise((r) => setTimeout(r, 0));
+    const finishedIdx = events.findIndex((e) => e.type === 'finished');
+    expect(finishedIdx).toBeGreaterThan(-1);
+    expect(events.filter((e) => e.type === 'finished')).toHaveLength(1);
+    const finished = events[finishedIdx];
+    expect(finished.type === 'finished' && finished.run.status).toBe('cancelled');
+    const childStatesAfter = events
+      .slice(finishedIdx + 1)
+      .filter((e) => e.type === 'nodeState' && e.workflowId === 'child-flow');
+    expect(childStatesAfter).toEqual([]);
+
+    // cancel of an unknown run reports false (route 404s).
+    expect(runs.cancel('nope')).toBe(false);
+  });
+
+  it('concurrent step() calls serialize: both resolve, in order, as two sequential steps', async () => {
+    const runs = new RunRegistry(flowStore([parentFlow, childFlow]), registry());
+    const { runId } = runs.create(parentFlow, { ...runOpts, input: { value: 3 }, stepped: true });
+
+    // Fired without awaiting between: without the per-run mutex the second
+    // call overwrites onChildStarted and the first request hangs.
+    const [r1, r2] = await Promise.all([runs.step(runId), runs.step(runId)]);
+    expect(r1).toEqual({ done: false }); // pin
+    expect(r2).toEqual({ done: false, entered: { workflowId: 'child-flow', nodeId: 'sub' } });
+
+    const rest = await stepToEnd(runs, runId);
+    expect(rest[rest.length - 1]).toEqual({ done: true });
+  });
+
+  it('non-stepped runs keep today’s behavior: no drill markers, child node states not streamed', async () => {
+    const runs = new RunRegistry(flowStore([parentFlow, childFlow]), registry());
+    const { runId, handle } = runs.create(parentFlow, { ...runOpts, input: { value: 5 } });
+
+    const events: RunEvent[] = [];
+    runs.subscribe(runId, (e) => events.push(e));
+
+    const seq = await stepToEnd(runs, runId);
+    expect(seq.every((s) => !s.entered && !s.exited)).toBe(true);
+    expect(handle.run.status).toBe('succeeded');
+    expect(
+      events.some((e) => e.type === 'nodeState' && e.workflowId === 'child-flow'),
+    ).toBe(false);
+  });
+});