@xdelivered/emberflow 0.2.0 → 0.5.0

package/src/store/builderStore.test.ts

@@ -1,11 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { pinsOf, useBuilderStore } from './builderStore';
 import { createLoginFlow } from '../flows/login-flow';
-import { createDefaultRegistry } from '../nodes';
 import * as serverRunner from './serverRunner';
 import * as agentClient from './agentClient';
-import type { WorkflowDefinition, WorkflowNode } from '../engine';
-import type { ScenarioTestReport, ServerRunHandlers } from './serverRunner';
+import type { WorkflowDefinition } from '../engine';
+import type { ScenarioTestReport, ServerRunHandlers, StepResult } from './serverRunner';
 
 vi.mock('./serverRunner', async () => {
   const actual = await vi.importActual<typeof import('./serverRunner')>('./serverRunner');
@@ -22,8 +21,10 @@ vi.mock('./serverRunner', async () => {
     runnerHealthy: vi.fn(),
     testWorkflow: vi.fn(),
     startServerRun: vi.fn(),
+    stepServerRun: vi.fn(),
     subscribeServerRun: vi.fn(),
     setServingMode: vi.fn(),
+    runNodeOnServer: vi.fn(),
   };
 });
 
@@ -173,18 +174,23 @@ describe('builderStore workflows', () => {
 
 describe('builderStore pinning', () => {
   beforeEach(() => {
-    useBuilderStore.setState({ flow: createLoginFlow(), run: null, logs: [], activeRun: null });
+    vi.mocked(serverRunner.startServerRun).mockReset().mockResolvedValue('run-p');
+    vi.mocked(serverRunner.subscribeServerRun).mockReset().mockImplementation(() => () => {});
+    useBuilderStore.setState({
+      flow: createLoginFlow(), run: null, logs: [], activeRun: null,
+      activeServerRunId: null, runnerOnline: true,
+    });
   });
 
-  it('pinned output skips execution and feeds downstream mapping', async () => {
+  it('threads pinned outputs to the server run (the runner honours the pin)', async () => {
     useBuilderStore
       .getState()
       .pinNodeOutput('validate', { userId: 'user-pinned', username: 'pinned' });
     await useBuilderStore.getState().runToEnd();
-    const run = useBuilderStore.getState().run!;
-    expect(run.nodeStates.validate.pinned).toBe(true);
-    expect((run.nodeStates.fetch.input as { userId: string }).userId).toBe('user-pinned');
-  }, 10_000);
+    // pins are startServerRun's 3rd arg (flow, mode, pins, input, options).
+    const pins = vi.mocked(serverRunner.startServerRun).mock.calls[0][2];
+    expect(pins).toEqual({ validate: { userId: 'user-pinned', username: 'pinned' } });
+  });
 
   it('unpinNode clears the pin and empties metadata', () => {
     useBuilderStore.getState().pinNodeOutput('validate', { userId: 'x' });
@@ -205,37 +211,66 @@ describe('builderStore pinning', () => {
   });
 });
 
-describe('builderStore isolated node run', () => {
+describe('builderStore isolated node run (server-backed)', () => {
   beforeEach(() => {
-    useBuilderStore.setState({ flow: createLoginFlow(), run: null, logs: [], activeRun: null });
+    vi.mocked(serverRunner.runNodeOnServer).mockReset();
+    useBuilderStore.setState({
+      flow: createLoginFlow(),
+      run: null,
+      logs: [],
+      activeRun: null,
+      runnerOnline: true,
+      selectedEnvironment: 'local',
+      safeMode: true,
+    });
   });
 
-  it('executes one node against supplied input, capturing logs and a sample', async () => {
+  it('calls the runner with the node type, input, config and env, and records a local sample', async () => {
+    vi.mocked(serverRunner.runNodeOnServer).mockResolvedValue({
+      output: { plan: 'pro' },
+      logs: [{ timestamp: 't', level: 'info', runId: 'node-run', message: 'plan pro' }],
+    });
     const before = useBuilderStore.getState().trace.samplesFor('checkPlan').length;
+
     const result = await useBuilderStore
       .getState()
       .runNodeIsolated('checkPlan', { user: { plan: 'pro' } });
+
     expect(result.error).toBeUndefined();
     expect((result.output as { plan: string }).plan).toBe('pro');
     expect(result.logs.some((l) => l.message.includes('pro'))).toBe(true);
+    const call = vi.mocked(serverRunner.runNodeOnServer).mock.calls[0][0];
+    // Sends the node TYPE (CheckPlan), not the node id (checkPlan).
+    expect(call.type).toBe('CheckPlan');
+    expect(call.input).toEqual({ user: { plan: 'pro' } });
+    expect(call.environment).toBe('local');
     const samples = useBuilderStore.getState().trace.samplesFor('checkPlan');
     expect(samples.length).toBe(before + 1);
     expect(samples[0].input).toEqual({ user: { plan: 'pro' } });
     expect(useBuilderStore.getState().run).toBeNull();
   });
 
-  it('reports node failure as error with a failed sample', async () => {
-    const result = await useBuilderStore
-      .getState()
-      .runNodeIsolated('validate', { username: 'ada', password: 'lovelace' });
-    expect(result.error).toBeUndefined();
-
+  it('surfaces a runner error as the result error and records a failed sample', async () => {
+    vi.mocked(serverRunner.runNodeOnServer).mockResolvedValue({
+      error: 'Password too short',
+      logs: [],
+    });
     const failed = await useBuilderStore
       .getState()
       .runNodeIsolated('validate', { username: 'ada', password: 'x' });
     expect(failed.error).toContain('Password too short');
     expect(useBuilderStore.getState().trace.samplesFor('validate')[0].status).toBe('failed');
   });
+
+  it('shows the offline notice when the runner is unreachable', async () => {
+    useBuilderStore.setState({ runnerOnline: false });
+    vi.mocked(serverRunner.runNodeOnServer).mockRejectedValue(new Error('Failed to fetch'));
+    const result = await useBuilderStore
+      .getState()
+      .runNodeIsolated('validate', { username: 'ada', password: 'x' });
+    expect(result.error).toContain('Runner offline');
+    expect(result.logs).toEqual([]);
+  });
 });
 
 describe('builderStore runner sync', () => {
@@ -428,6 +463,8 @@ describe('builderStore run history', () => {
 
 describe('builderStore scenarios', () => {
   beforeEach(() => {
+    vi.mocked(serverRunner.startServerRun).mockReset().mockResolvedValue('run-s');
+    vi.mocked(serverRunner.subscribeServerRun).mockReset().mockImplementation(() => () => {});
     // Start from a scenario-free flow: the seeded examples would offset counts.
     const flow = createLoginFlow();
     delete flow.scenarios;
@@ -436,9 +473,10 @@ describe('builderStore scenarios', () => {
       run: null,
       logs: [],
       activeRun: null,
+      activeServerRunId: null,
       runHistory: [],
       activeScenarioId: null,
-      executionMode: 'browser',
+      runnerOnline: true,
     });
   });
 
@@ -458,7 +496,12 @@ describe('builderStore scenarios', () => {
     expect(useBuilderStore.getState().flow.scenarios).toBeUndefined();
   });
 
-  it('runScenario feeds the payload through the Input node and tags history', async () => {
+  it('runScenario starts a server run with the scenario payload + name and tags history', async () => {
+    let capturedHandlers: ServerRunHandlers | undefined;
+    vi.mocked(serverRunner.subscribeServerRun).mockImplementation((_runId, handlers) => {
+      capturedHandlers = handlers;
+      return () => {};
+    });
     useBuilderStore
       .getState()
       .addScenario('new user', { username: 'newton', password: 'apple123' });
@@ -466,25 +509,50 @@ describe('builderStore scenarios', () => {
 
     await useBuilderStore.getState().runScenario(id);
 
-    const run = useBuilderStore.getState().run!;
-    expect(run.status).toBe('succeeded');
-    expect((run.nodeStates.input.output as { username: string }).username).toBe('newton');
-    // 'newton' is a new user: the welcome branch fires and checkPlan is skipped.
-    expect(run.nodeStates.welcome.status).toBe('succeeded');
-    expect(run.nodeStates.checkPlan.status).toBe('skipped');
+    const call = vi.mocked(serverRunner.startServerRun).mock.calls[0];
+    expect(call[1]).toBe('run');
+    expect(call[3]).toEqual({ username: 'newton', password: 'apple123' });
+    expect(call[4]).toMatchObject({ scenarioName: 'new user' });
+
+    const flowId = useBuilderStore.getState().flow.id;
+    capturedHandlers!.onFinished({
+      id: 'run-s',
+      workflowId: flowId,
+      status: 'succeeded',
+      startedAt: '2026-07-10T10:00:00Z',
+      completedAt: '2026-07-10T10:00:01Z',
+      nodeStates: {},
+    });
     expect(useBuilderStore.getState().runHistory[0].scenarioName).toBe('new user');
-  }, 15_000);
+  });
 
   it('a plain run after a scenario run is not tagged', async () => {
+    const handlersByRun: Record<string, ServerRunHandlers> = {};
+    vi.mocked(serverRunner.subscribeServerRun).mockImplementation((runId, handlers) => {
+      handlersByRun[runId] = handlers;
+      return () => {};
+    });
     useBuilderStore
       .getState()
       .addScenario('new user', { username: 'newton', password: 'apple123' });
     const id = useBuilderStore.getState().flow.scenarios![0].id;
+    const flowId = useBuilderStore.getState().flow.id;
+
+    vi.mocked(serverRunner.startServerRun).mockResolvedValueOnce('run-a');
     await useBuilderStore.getState().runScenario(id);
+    handlersByRun['run-a'].onFinished({
+      id: 'run-a', workflowId: flowId, status: 'succeeded',
+      startedAt: '2026-07-10T10:00:00Z', completedAt: '2026-07-10T10:00:01Z', nodeStates: {},
+    });
 
+    vi.mocked(serverRunner.startServerRun).mockResolvedValueOnce('run-b');
     await useBuilderStore.getState().runToEnd();
+    handlersByRun['run-b'].onFinished({
+      id: 'run-b', workflowId: flowId, status: 'succeeded',
+      startedAt: '2026-07-10T10:00:02Z', completedAt: '2026-07-10T10:00:03Z', nodeStates: {},
+    });
     expect(useBuilderStore.getState().runHistory[0].scenarioName).toBeUndefined();
-  }, 20_000);
+  });
 });
 
 describe('builderStore environments + safe mode', () => {
@@ -665,6 +733,103 @@ describe('builderStore agent picker', () => {
       .runAgent({ action: 'edit-flow', flowId: 'f1', instruction: 'go' }, { model: 'other' });
     expect(agentClient.startAgent).toHaveBeenCalledWith(expect.anything(), { model: 'other' });
   });
+
+  it('beginInfrastructureScout: a leaked MouseEvent (onClick wiring) falls back to the full-rescan instruction', () => {
+    // Regression: the Dock's scout button once passed the click event as
+    // `instruction`, crashing on instruction.trim(). Non-strings = full rescan.
+    useBuilderStore.getState().beginInfrastructureScout(
+      { type: 'click' } as unknown as string,
+    );
+    expect(agentClient.startAgent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: 'scout-infrastructure',
+        instruction: expect.stringContaining('Scan this project'),
+      }),
+      expect.anything(),
+    );
+  });
+
+  it('beginInfrastructureScout: a real instruction threads verbatim', () => {
+    useBuilderStore.getState().beginInfrastructureScout('add our Redis cache');
+    expect(agentClient.startAgent).toHaveBeenCalledWith(
+      expect.objectContaining({ instruction: 'add our Redis cache' }),
+      expect.anything(),
+    );
+  });
+});
+
+describe('builderStore guided setup transcript', () => {
+  beforeEach(() => {
+    vi.mocked(agentClient.startAgent).mockClear().mockResolvedValue('run-1');
+    useBuilderStore.setState({ agentChoice: {}, agentRun: null, guidedTranscript: [] });
+  });
+
+  const QUESTION_TEXT =
+    'Two things to decide.\n\n' +
+    '```emberflow-questions\n{"questions":[{"id":"envs","text":"Which environments?","options":["dev + prod"]}]}\n```\n';
+
+  it('continuation: appends the prior guided run (question blocks stripped) + a **You:** message', () => {
+    useBuilderStore.setState({
+      guidedTranscript: [{ type: 'message', text: 'Earlier turn.' }],
+      agentRun: {
+        id: 'run-0',
+        status: 'done',
+        guided: true,
+        events: [
+          { type: 'message', text: 'Reading the ground truth first.' },
+          { type: 'command', command: 'git status', commandStatus: 'completed' },
+          { type: 'message', text: QUESTION_TEXT },
+        ],
+      },
+    });
+
+    useBuilderStore.getState().beginGuidedSetup('Which environments?: dev + prod');
+
+    expect(useBuilderStore.getState().guidedTranscript).toEqual([
+      { type: 'message', text: 'Earlier turn.' },
+      { type: 'message', text: 'Reading the ground truth first.' },
+      { type: 'command', command: 'git status', commandStatus: 'completed' },
+      // The answered question block is stripped — only the prose survives.
+      { type: 'message', text: 'Two things to decide.' },
+      { type: 'message', text: '**You:** Which environments?: dev + prod' },
+    ]);
+    expect(agentClient.startAgent).toHaveBeenCalledWith(
+      { action: 'guided-setup', instruction: 'Which environments?: dev + prod' },
+      expect.anything(),
+    );
+  });
+
+  it('fresh start (no notes) clears the transcript', () => {
+    useBuilderStore.setState({
+      guidedTranscript: [{ type: 'message', text: 'Stale conversation.' }],
+    });
+    useBuilderStore.getState().beginGuidedSetup();
+    expect(useBuilderStore.getState().guidedTranscript).toEqual([]);
+    expect(agentClient.startAgent).toHaveBeenCalledWith(
+      { action: 'guided-setup', instruction: '' },
+      expect.anything(),
+    );
+  });
+
+  it('a leaked MouseEvent (onClick wiring) counts as a fresh start, not a continuation', () => {
+    useBuilderStore.setState({
+      guidedTranscript: [{ type: 'message', text: 'Stale conversation.' }],
+      agentRun: { id: 'run-0', status: 'done', guided: true, events: [] },
+    });
+    useBuilderStore.getState().beginGuidedSetup({ type: 'click' } as unknown as string);
+    expect(useBuilderStore.getState().guidedTranscript).toEqual([]);
+  });
+
+  it('notes without a prior guided run leave the transcript untouched', () => {
+    useBuilderStore.setState({
+      guidedTranscript: [{ type: 'message', text: 'Kept.' }],
+      agentRun: { id: 'run-9', status: 'done', events: [{ type: 'message', text: 'edit-flow run' }] },
+    });
+    useBuilderStore.getState().beginGuidedSetup('an answer');
+    expect(useBuilderStore.getState().guidedTranscript).toEqual([
+      { type: 'message', text: 'Kept.' },
+    ]);
+  });
 });
 
 describe('builderStore node sizing', () => {
@@ -924,75 +1089,8 @@ describe('builderStore run console dismissal', () => {
 // the toolbar's visual reflection of it, is only verifiable in a rendered
 // browser/component-test environment, not from the store alone.
 
-describe('builderStore subflow execution', () => {
-  const node = (id: string, type: string, extra: Partial<WorkflowNode> = {}): WorkflowNode => ({
-    id, type, label: id, position: { x: 0, y: 0 }, config: {}, ...extra,
-  });
-  const mkFlow = (
-    id: string, name: string, nodes: WorkflowNode[], edges: WorkflowDefinition['edges'],
-  ): WorkflowDefinition => ({
-    id, name, version: 1, nodes, edges,
-    createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z',
-  });
-
-  beforeEach(() => {
-    // Delay-free registry so end-to-end runs are fast; browser mode so runs
-    // execute in-tab through the store's subflow runner.
-    useBuilderStore.setState({
-      registry: createDefaultRegistry(0),
-      runnerOnline: false,
-      executionMode: 'browser',
-      run: null,
-      logs: [],
-      activeRun: null,
-      activeServerRunId: null,
-    });
-  });
-
-  it('resolves a shelf workflow and forwards its logs with prefixing', async () => {
-    const child = mkFlow('child', 'Child', [node('cres', 'Result', { label: 'Result' })], []);
-    const parent = mkFlow(
-      'parent', 'Parent',
-      [
-        node('sub', 'Subflow', { config: { workflowId: 'child' } }),
-        node('res', 'Result', { inputMap: { data: { sourceNodeId: 'sub', sourceField: '$' } } }),
-      ],
-      [{ id: 'e', source: 'sub', target: 'res', targetHandle: 'data' }],
-    );
-    useBuilderStore.setState({ flow: parent, shelf: [child] });
-
-    await useBuilderStore.getState().runToEnd();
-    const s = useBuilderStore.getState();
-    expect(s.run?.status).toBe('succeeded');
-    expect(s.run?.nodeStates.sub.status).toBe('succeeded');
-    // The child's Result-collected output flows into the parent's Result.
-    expect(s.run?.nodeStates.res.output).toEqual({ data: {} });
-
-    const forwarded = s.logs.find((l) => l.nodeId === 'sub/cres');
-    expect(forwarded, JSON.stringify(s.logs)).toBeDefined();
-    expect(forwarded?.nodeLabel).toBe('Child › Result');
-  });
-
-  it('rejects an unknown workflow id', async () => {
-    const parent = mkFlow('parent', 'Parent', [node('sub', 'Subflow', { config: { workflowId: 'nope' } })], []);
-    useBuilderStore.setState({ flow: parent, shelf: [] });
-    await useBuilderStore.getState().runToEnd();
-    const s = useBuilderStore.getState();
-    expect(s.run?.status).toBe('failed');
-    expect(s.run?.nodeStates.sub.error).toBe('Unknown workflow: nope');
-  });
-
-  it('catches an A→B→A cycle at runtime', async () => {
-    const a = mkFlow('a', 'A', [node('subA', 'Subflow', { config: { workflowId: 'b' } })], []);
-    const b = mkFlow('b', 'B', [node('subB', 'Subflow', { config: { workflowId: 'a' } })], []);
-    useBuilderStore.setState({ flow: a, shelf: [b] });
-    await useBuilderStore.getState().runToEnd();
-    const s = useBuilderStore.getState();
-    expect(s.run?.status).toBe('failed');
-    // The cycle is reported from deep in the child; its error log is forwarded up.
-    expect(s.logs.some((l) => l.message === 'subflow cycle: a → b → a')).toBe(true);
-  });
-});
+// Subflow execution moved server-side (server/subflowRunner.ts, exercised by the
+// runner's run tests) — the studio no longer runs child workflows in-tab.
 
 describe('builderStore.syncNodeMeta', () => {
   afterEach(() => vi.unstubAllGlobals());
@@ -1097,7 +1195,6 @@ describe('builderStore mock runs (studio wiring)', () => {
       logs: [],
       activeRun: null,
       activeServerRunId: null,
-      executionMode: 'server',
       runnerOnline: true,
       runnerMock: true,
       runHistory: [],
@@ -1174,7 +1271,6 @@ describe('builderStore server-run finished event → errorHandler tag', () => {
       logs: [],
       activeRun: null,
       activeServerRunId: null,
-      executionMode: 'server',
       runnerOnline: true,
       runHistory: [],
       activeScenarioId: null,
@@ -1232,3 +1328,249 @@ describe('builderStore server-run finished event → errorHandler tag', () => {
     expect(entry?.errorHandler).toBeUndefined();
   });
 });
+
+describe('builderStore subflow step drill-in', () => {
+  const drillFlow = (id: string, name: string, nodeIds: string[]): WorkflowDefinition => ({
+    id,
+    name,
+    version: 1,
+    nodes: nodeIds.map((nid, i) => ({
+      id: nid,
+      type: 'Noop',
+      label: nid,
+      position: { x: i * 100, y: 0 },
+      config: {},
+    })),
+    edges: [],
+    createdAt: '2026-07-13T00:00:00Z',
+    updatedAt: '2026-07-13T00:00:00Z',
+  });
+
+  let handlers: ServerRunHandlers | undefined;
+
+  beforeEach(() => {
+    handlers = undefined;
+    vi.mocked(serverRunner.startServerRun).mockReset().mockResolvedValue('run-d');
+    vi.mocked(serverRunner.stepServerRun).mockReset();
+    vi.mocked(serverRunner.subscribeServerRun).mockReset().mockImplementation((_runId, h) => {
+      handlers = h;
+      return () => {};
+    });
+    useBuilderStore.setState({
+      flow: drillFlow('parent', 'Parent Flow', ['start', 'sub', 'finish']),
+      shelf: [drillFlow('child', 'Child Flow', ['c1', 'c2']), drillFlow('grandchild', 'Grandchild Flow', ['g1'])],
+      run: null,
+      logs: [],
+      activeRun: null,
+      activeServerRunId: null,
+      runnerOnline: true,
+      runHistory: [],
+      activeScenarioId: null,
+      stepMode: false,
+      stepDrill: [],
+      drillPeek: null,
+      selectedNodeId: null,
+    });
+  });
+
+  /** One Step click: queue the next step response and drive stepRun. */
+  const step = (result: StepResult): Promise<void> => {
+    vi.mocked(serverRunner.stepServerRun).mockResolvedValueOnce(result);
+    return useBuilderStore.getState().stepRun();
+  };
+
+  it('entered pushes a drill level, swaps the view to the child, and routes nodeState by workflowId', async () => {
+    await step({ done: false }); // first parent node
+    await step({ done: false, entered: { workflowId: 'child', nodeId: 'sub' } });
+
+    let s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('child');
+    expect(s.stepDrill).toHaveLength(1);
+    expect(s.stepDrill[0]).toMatchObject({ workflowId: 'child', viaNodeId: 'sub' });
+    expect(s.stepDrill[0].savedFlow.id).toBe('parent');
+    // Synthetic child run: running, no node states yet (first child node runs
+    // on the NEXT step), same id as the root run so SSE routing applies.
+    expect(s.run?.workflowId).toBe('child');
+    expect(s.run?.status).toBe('running');
+    expect(s.run?.nodeStates).toEqual({});
+    expect(s.run?.id).toBe('run-d');
+    // The live server run and step mode are untouched by drilling.
+    expect(s.activeServerRunId).toBe('run-d');
+    expect(s.stepMode).toBe(true);
+
+    // Child workflowId → lights the visible (child) run.
+    handlers!.onNodeState('child', 'c1', { status: 'running' });
+    expect(useBuilderStore.getState().run?.nodeStates.c1?.status).toBe('running');
+
+    // Parent workflowId → lands on the stashed parent run, not the child view.
+    handlers!.onNodeState('parent', 'sub', { status: 'running' });
+    s = useBuilderStore.getState();
+    expect(s.run?.nodeStates.sub).toBeUndefined();
+    expect(s.stepDrill[0].savedRun?.nodeStates.sub?.status).toBe('running');
+
+    // Unknown workflowId → ignored.
+    handlers!.onNodeState('elsewhere', 'x', { status: 'running' });
+    expect(useBuilderStore.getState().run?.nodeStates.x).toBeUndefined();
+  });
+
+  it('drilling does not clear the root run logs', async () => {
+    await step({ done: false });
+    useBuilderStore.setState({
+      logs: [{ timestamp: 't', level: 'info', runId: 'run-d', message: 'parent log' }],
+    });
+    await step({ done: false, entered: { workflowId: 'child', nodeId: 'sub' } });
+    expect(useBuilderStore.getState().logs.map((l) => l.message)).toEqual(['parent log']);
+  });
+
+  it('exited restores the parent view including its updated Subflow node state and selection', async () => {
+    await step({ done: false });
+    useBuilderStore.setState({ selectedNodeId: 'start' });
+    await step({ done: false, entered: { workflowId: 'child', nodeId: 'sub' } });
+    expect(useBuilderStore.getState().selectedNodeId).toBeNull();
+
+    handlers!.onNodeState('child', 'c1', { status: 'succeeded' });
+    handlers!.onNodeState('parent', 'sub', { status: 'succeeded' });
+    await step({ done: false, exited: true });
+
+    const s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('parent');
+    expect(s.stepDrill).toHaveLength(0);
+    expect(s.run?.workflowId).toBe('parent');
+    expect(s.run?.nodeStates.sub?.status).toBe('succeeded');
+    expect(s.selectedNodeId).toBe('start');
+  });
+
+  it('nested enter/enter/exit/exit walks the stack one level at a time', async () => {
+    await step({ done: false, entered: { workflowId: 'child', nodeId: 'sub' } });
+    await step({ done: false, entered: { workflowId: 'grandchild', nodeId: 'c2' } });
+
+    let s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('grandchild');
+    expect(s.stepDrill.map((d) => d.workflowId)).toEqual(['child', 'grandchild']);
+    expect(s.stepDrill[1].savedFlow.id).toBe('child');
+
+    // Mid-level (child) states land on its stashed run while two deep.
+    handlers!.onNodeState('child', 'c2', { status: 'running' });
+    s = useBuilderStore.getState();
+    expect(s.stepDrill[1].savedRun?.nodeStates.c2?.status).toBe('running');
+
+    await step({ done: false, exited: true });
+    s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('child');
+    expect(s.stepDrill).toHaveLength(1);
+    expect(s.run?.nodeStates.c2?.status).toBe('running');
+
+    await step({ done: false, exited: true });
+    s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('parent');
+    expect(s.stepDrill).toHaveLength(0);
+  });
+
+  it('entered with an unknown child flow id stays on the parent but pushes a placeholder level', async () => {
+    await step({ done: false, entered: { workflowId: 'missing', nodeId: 'sub' } });
+    let s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('parent');
+    // The server's drill stack grew — the client mirrors the depth with a
+    // placeholder so the matching `exited` pops the right level.
+    expect(s.stepDrill).toHaveLength(1);
+    expect(s.stepDrill[0]).toMatchObject({ workflowId: 'missing', viaNodeId: 'sub', placeholder: true });
+    expect(s.stepDrill[0].savedFlow.id).toBe('parent');
+
+    // Parent states keep applying to the visible run as before.
+    handlers!.onNodeState('parent', 'sub', { status: 'running' });
+    expect(useBuilderStore.getState().run?.nodeStates.sub?.status).toBe('running');
+
+    // The matching exited pops the placeholder and leaves the parent view —
+    // including states received while "inside" — untouched.
+    await step({ done: false, exited: true });
+    s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('parent');
+    expect(s.stepDrill).toHaveLength(0);
+    expect(s.run?.nodeStates.sub?.status).toBe('running');
+  });
+
+  it('exited+entered in one step (Subflow retry) pops the failed child before pushing the fresh one', async () => {
+    await step({ done: false, entered: { workflowId: 'child', nodeId: 'sub' } });
+    expect(useBuilderStore.getState().flow.id).toBe('child');
+
+    // The retrying Subflow node pops its failed child AND re-enters a new
+    // child run in the same composite step.
+    await step({ done: false, exited: true, entered: { workflowId: 'child', nodeId: 'sub' } });
+    const s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('child');
+    expect(s.stepDrill).toHaveLength(1);
+    expect(s.stepDrill[0].savedFlow.id).toBe('parent');
+    // Fresh synthetic child run for the retry attempt.
+    expect(s.run?.workflowId).toBe('child');
+    expect(s.run?.nodeStates).toEqual({});
+
+    await step({ done: false, exited: true });
+    expect(useBuilderStore.getState().flow.id).toBe('parent');
+    expect(useBuilderStore.getState().stepDrill).toHaveLength(0);
+  });
+
+  it('exited plus done pops the drill and ends the live run', async () => {
+    await step({ done: false, entered: { workflowId: 'child', nodeId: 'sub' } });
+    await step({ done: true, exited: true });
+    const s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('parent');
+    expect(s.stepDrill).toHaveLength(0);
+    expect(s.activeServerRunId).toBeNull();
+  });
+
+  it('peek shows an ancestor without popping; child states during the peek still land on the child run', async () => {
+    await step({ done: false, entered: { workflowId: 'child', nodeId: 'sub' } });
+
+    useBuilderStore.getState().peekDrill(0);
+    let s = useBuilderStore.getState();
+    expect(s.drillPeek).toBe(0);
+    // View-only: the drill stack and the live (deepest) level are untouched —
+    // the runbook derives the peeked flow/run from stepDrill[drillPeek].
+    expect(s.stepDrill).toHaveLength(1);
+    expect(s.flow.id).toBe('child');
+    expect(s.stepDrill[0].savedFlow.id).toBe('parent');
+
+    // Child states arriving during the peek land on the child's (live) run.
+    handlers!.onNodeState('child', 'c1', { status: 'succeeded' });
+    expect(useBuilderStore.getState().run?.nodeStates.c1?.status).toBe('succeeded');
+    // Parent states still land on the stashed parent run.
+    handlers!.onNodeState('parent', 'sub', { status: 'running' });
+    expect(useBuilderStore.getState().stepDrill[0].savedRun?.nodeStates.sub?.status).toBe('running');
+
+    // The last crumb returns to the deepest level.
+    useBuilderStore.getState().peekDrill(null);
+    expect(useBuilderStore.getState().drillPeek).toBeNull();
+
+    // Out-of-range peek indexes clear rather than dangle.
+    useBuilderStore.getState().peekDrill(7);
+    expect(useBuilderStore.getState().drillPeek).toBeNull();
+  });
+
+  it('a further entered while peeking resets the peek to the new deepest level', async () => {
+    await step({ done: false, entered: { workflowId: 'child', nodeId: 'sub' } });
+    useBuilderStore.getState().peekDrill(0);
+    await step({ done: false, entered: { workflowId: 'grandchild', nodeId: 'c2' } });
+    const s = useBuilderStore.getState();
+    expect(s.drillPeek).toBeNull();
+    expect(s.flow.id).toBe('grandchild');
+    expect(s.stepDrill).toHaveLength(2);
+  });
+
+  it('the finished SSE event unwinds any remaining drill before recording the root run', async () => {
+    await step({ done: false, entered: { workflowId: 'child', nodeId: 'sub' } });
+    handlers!.onFinished({
+      id: 'run-d',
+      workflowId: 'parent',
+      status: 'failed',
+      startedAt: '2026-07-13T10:00:00Z',
+      completedAt: '2026-07-13T10:00:01Z',
+      nodeStates: {},
+    });
+    const s = useBuilderStore.getState();
+    expect(s.flow.id).toBe('parent');
+    expect(s.stepDrill).toHaveLength(0);
+    expect(s.run?.id).toBe('run-d');
+    expect(s.run?.workflowId).toBe('parent');
+    expect(s.runHistory[0]?.id).toBe('run-d');
+  });
+});