@xdelivered/emberflow 0.2.0 → 0.5.0

package/server/sourceNavRoute.test.ts

@@ -0,0 +1,163 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// End-to-end coverage of GET /source-file plus the nodesPayload sourceRef
+// wiring, through the real runner subprocess (same harness as
+// diagnosticsRoute.test.ts). Uses the regression fixture shape:
+// DeriveShipmentActuals registered from nodes.mjs, whose handler imports
+// deriveTrackingActual from shipment-logic.mjs.
+
+let proc: ChildProcess;
+const PORT = 8157;
+const base = `http://127.0.0.1:${PORT}`;
+let projectDir: string;
+
+async function waitHealthy(url: string, tries = 40): Promise<void> {
+  for (let i = 0; i < tries; i++) {
+    try {
+      if ((await fetch(url)).ok) return;
+    } catch {
+      /* not up yet */
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error('runner did not become healthy');
+}
+
+function sourceFileUrl(path: string): string {
+  return `${base}/api/source-file?${new URLSearchParams({ path })}`;
+}
+
+beforeAll(async () => {
+  projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'sourcenavroute-')));
+  const w = (rel: string, content: string): void => writeFileSync(join(projectDir, rel), content);
+  w(
+    'shipment-logic.mjs',
+    [
+      'function nestedHelper(shipment) {', // 1
+      '  return (shipment.weight ?? 0) * 2;', // 2
+      '}', // 3
+      '', // 4
+      'export function deriveTrackingActual(shipment) {', // 5
+      '  return nestedHelper(shipment);', // 6
+      '}', // 7
+      '',
+    ].join('\n'),
+  );
+  w(
+    'nodes.mjs',
+    [
+      "import { deriveTrackingActual } from './shipment-logic.mjs';", // 1
+      '', // 2
+      'export function registerNodes(registry) {', // 3
+      '  registry.register(', // 4
+      "    { type: 'DeriveShipmentActuals', label: 'Derive Shipment Actuals' },", // 5
+      '    async (ctx) => ({ actual: deriveTrackingActual(ctx.input) }),', // 6
+      '  );', // 7
+      '}', // 8
+      '',
+    ].join('\n'),
+  );
+  w(
+    'emberflow.config.mjs',
+    ["import { registerNodes } from './nodes.mjs';", 'export default { registerNodes };', ''].join(
+      '\n',
+    ),
+  );
+  w('.env', 'TOP_SECRET=shh\n');
+
+  proc = spawn('npx', ['tsx', 'server/index.ts'], {
+    env: {
+      ...process.env,
+      EMBERFLOW_RUNNER_PORT: String(PORT),
+      EMBERFLOW_PROJECT: projectDir,
+    },
+    stdio: 'ignore',
+  });
+  await waitHealthy(`${base}/healthz`);
+}, 20_000);
+
+afterAll(() => {
+  proc?.kill();
+  if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('GET /nodes sourceRef wiring', () => {
+  it('carries a repo-relative sourceRef for the project node and builtin flag for package nodes', async () => {
+    const res = await fetch(`${base}/api/nodes`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      nodes: Array<{ type: string; sourceRef?: { file: string; line?: number }; builtin?: boolean }>;
+    };
+    const project = body.nodes.find((n) => n.type === 'DeriveShipmentActuals');
+    expect(project).toBeDefined();
+    expect(project!.sourceRef).toEqual({ file: 'nodes.mjs', line: 4 });
+    expect(project!.builtin).toBeUndefined();
+
+    const builtin = body.nodes.find((n) => n.type === 'ValidateCredentials');
+    expect(builtin).toBeDefined();
+    expect(builtin!.builtin).toBe(true);
+    expect(builtin!.sourceRef).toBeUndefined();
+  });
+});
+
+describe('GET /source-file', () => {
+  it('serves the handler module with the imported helper resolved to its project file', async () => {
+    const res = await fetch(sourceFileUrl('nodes.mjs'));
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      path: string;
+      content: string;
+      language: string;
+      symbols: {
+        imports: Array<{ local: string; resolution: { kind: string; path?: string; line?: number } }>;
+      };
+    };
+    expect(body.path).toBe('nodes.mjs');
+    expect(body.language).toBe('js');
+    expect(body.content).toContain('DeriveShipmentActuals');
+    const imp = body.symbols.imports.find((i) => i.local === 'deriveTrackingActual');
+    expect(imp!.resolution).toEqual({ kind: 'project', path: 'shipment-logic.mjs', line: 5 });
+  });
+
+  it('exposes declaration lines on the helper module', async () => {
+    const res = await fetch(sourceFileUrl('shipment-logic.mjs'));
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      symbols: {
+        declarations: Array<{ name: string; line: number; endLine: number; exported: boolean }>;
+      };
+    };
+    const derive = body.symbols.declarations.find((d) => d.name === 'deriveTrackingActual');
+    expect(derive).toMatchObject({ line: 5, endLine: 7, exported: true });
+  });
+
+  it('400s on a traversal path without echoing it', async () => {
+    const res = await fetch(sourceFileUrl('../../etc/passwd'));
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).not.toContain('passwd');
+  });
+
+  it('400s on secret basenames and node_modules paths', async () => {
+    for (const p of ['.env', 'node_modules/x/index.js']) {
+      const res = await fetch(sourceFileUrl(p));
+      expect(res.status).toBe(400);
+      const body = (await res.json()) as { error: string };
+      expect(body.error).not.toContain(p);
+    }
+  });
+
+  it('400s when the path param is missing', async () => {
+    const res = await fetch(`${base}/api/source-file`);
+    expect(res.status).toBe(400);
+  });
+
+  it('404s for a missing file inside the project', async () => {
+    const res = await fetch(sourceFileUrl('missing.mjs'));
+    expect(res.status).toBe(404);
+  });
+});

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);
+  });
+});

package/server/subflowRunner.ts

@@ -1,16 +1,57 @@
 import type {
+  FlowRun,
   LogLine,
   NodeRegistry,
+  NodeRunState,
   StartRunOptions,
   SubflowResult,
   TraceSink,
   WorkflowDefinition,
+  WorkflowRun,
 } from '../src/engine';
 import { runOutput, startRun } from '../src/engine';
 
 /** Max depth of nested Subflow calls (ancestry chain length) before a run fails. */
 export const SUBFLOW_DEPTH_CAP = 8;
 
+/**
+ * One live drilled-into child on a stepped run. Pushed by the subflow runner
+ * when a Subflow node starts its child; popped by the registry's composite
+ * step() when the child's own stepping completes. `resolve`/`reject` settle
+ * the promise the parent's Subflow node execution is blocked on.
+ */
+export interface DrillEntry {
+  handle: FlowRun;
+  /** The child flow's id (what the caller drilled into). */
+  workflowId: string;
+  /** The parent Subflow node that triggered the child. */
+  viaNodeId: string;
+  /** Hands the completed child run back to the blocked parent Subflow node. */
+  resolve: (run: WorkflowRun) => void;
+  reject: (err: unknown) => void;
+  /**
+   * This level's own executor.step() promise, left pending while a DEEPER
+   * child runs (a Subflow node's execution blocks on its child). Stashed by
+   * the registry when it observes `entered`; folded back in on exit.
+   */
+  pendingStep?: Promise<boolean>;
+}
+
+/**
+ * Per-root-run drill state for stepped runs. The root's subflow runner and
+ * every nested child's runner share the SAME instance, so grandchildren push
+ * onto the same stack and nesting Just Works.
+ */
+export interface DrillState {
+  stack: DrillEntry[];
+  /** Armed by the registry's step() while it awaits a level's step, so a
+   *  child starting can be raced against the (now blocked) step promise. */
+  onChildStarted?: (entry: DrillEntry) => void;
+  /** Set by RunRegistry.cancel(): unwinding parent executions must not start
+   *  (or block on) new children — runSubflow fails fast instead. */
+  cancelled?: boolean;
+}
+
 export interface SubflowRunnerOptions {
   /** Resolves a child workflow by id (server hosts this via apiStore.load). */
   loadFlow: (id: string) => WorkflowDefinition | undefined;
@@ -29,6 +70,17 @@ export interface SubflowRunnerOptions {
    *  prefixed with the child flow's name and the caller node's id, exactly as
    *  the live runner streams them over SSE. Absent for headless runs. */
   onLog?: (line: LogLine) => void;
+  /**
+   * Present only for stepped runs: children become step-drivable instead of
+   * running to completion. The runner pushes each started child onto
+   * `drill.stack` and blocks the Subflow node until the registry pops it.
+   */
+  drill?: DrillState;
+  /** Child nodeState forwarder for stepped runs — receives the CHILD flow's
+   *  id so the client can route states to the drilled-in view. Only wired
+   *  when `drill` is present (non-stepped children keep today's behavior:
+   *  their node states are discarded, only the output returns). */
+  onNodeState?: (workflowId: string, nodeId: string, state: NodeRunState) => void;
 }
 
 /**
@@ -45,6 +97,11 @@ export function makeSubflowRunner(
   ancestry: string[],
 ): NonNullable<StartRunOptions['subflowRunner']> {
   return async (workflowId, input, callerNodeId): Promise<SubflowResult> => {
+    // A cancelled stepped run's unwinding parents (their runSubflow was
+    // rejected) may retry: never push a new child that nothing will step.
+    if (opts.drill?.cancelled) {
+      return { status: 'failed', error: 'run cancelled' };
+    }
     if (ancestry.length >= SUBFLOW_DEPTH_CAP) {
       return { status: 'failed', error: `subflow depth cap (${SUBFLOW_DEPTH_CAP}) exceeded` };
     }
@@ -72,18 +129,42 @@ export function makeSubflowRunner(
         mocks: (childFlow as { mocks?: Record<string, unknown> }).mocks ?? {},
         trace: opts.trace,
         subflowRunner: makeSubflowRunner(opts, [...ancestry, workflowId]),
-        events: opts.onLog
-          ? {
-              onLog: (line) =>
-                opts.onLog!({
-                  ...line,
-                  nodeLabel: `${childFlow.name} › ${line.nodeLabel ?? ''}`,
-                  nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
-                }),
-            }
-          : undefined,
+        events:
+          opts.onLog || (opts.drill && opts.onNodeState)
+            ? {
+                ...(opts.onLog
+                  ? {
+                      onLog: (line: LogLine) =>
+                        opts.onLog!({
+                          ...line,
+                          nodeLabel: `${childFlow.name} › ${line.nodeLabel ?? ''}`,
+                          nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
+                        }),
+                    }
+                  : {}),
+                // Stepped children stream their node states into the ROOT
+                // run's SSE stream, tagged with the child flow's id.
+                ...(opts.drill && opts.onNodeState
+                  ? {
+                      onNodeStateChange: (nodeId: string, state: NodeRunState) =>
+                        opts.onNodeState!(childFlow.id, nodeId, state),
+                    }
+                  : {}),
+              }
+            : undefined,
       });
-      const childRun = await childHandle.runToEnd();
+      // Stepped run: don't run the child here. Push it onto the shared drill
+      // stack and block this Subflow node until the registry's composite
+      // step() drives the child to completion and pops the entry — resolving
+      // with the completed child run, which flows into the exact same
+      // output-extraction / failure-mapping path runToEnd feeds today.
+      const childRun = opts.drill
+        ? await new Promise<WorkflowRun>((resolve, reject) => {
+            const entry: DrillEntry = { handle: childHandle, workflowId, viaNodeId: callerNodeId, resolve, reject };
+            opts.drill!.stack.push(entry);
+            opts.drill!.onChildStarted?.(entry);
+          })
+        : await childHandle.runToEnd();
       if (childRun.status !== 'succeeded') {
         // Surface the child's actual failure (e.g. the Mock-mode "would touch
         // real infrastructure" boundary message) through the Subflow node's