peachsim 0.1.1619 → 0.1.1625

package/cli/bridge-flow-runner.ts

@@ -22,6 +22,10 @@ import { PERMISSION_KINDS } from './commands/permissions'
 import { saveCurrentSimId } from './current-sim'
 import { parseFlowFile } from './flow-file'
 import { FlowLiveStatusReporter } from './flow-live-status'
+import {
+  accessibilityBounds,
+  sameNativeAccessibilityShape,
+} from './maestro-accessibility'
 import { MaestroJsContext, scriptConditionIsTruthy } from './maestro-js'
 import { ensureCliRecordingEntitlement } from './recording-access'
 import type { PerformResult, PerformStep, ResetResult } from '../src/bridge-contract'
@@ -43,8 +47,42 @@ const DEFAULT_TIMEOUT = 10000
 // how long maestro looks for a required assertion's element, counted from the
 // latest interaction (Orchestra lookupTimeoutMs and adjustedToLatestInteraction)
 const ASSERTION_LOOKUP_MS = 17_000
+// commands Orchestra.executeCommand reports as not mutating the device, so
+// they leave the lookup window running; every other command restarts it. the
+// last four are Peach observations with no device effect.
+const NON_MUTATING_STEPS = [
+  'assertTrue',
+  'assertVisible',
+  'assertNotVisible',
+  'extendedWaitUntil',
+  'takeScreenshot',
+  'setClipboard',
+  'copyTextFrom',
+  'clearKeychain',
+  'waitFor',
+  'wait',
+  'dumpTree',
+  'assertTreeContains',
+] as const satisfies readonly (keyof MaestroStep)[]
 const FLOW_TIMEOUT_SCALE = flowTimeoutScale()
 const scaledTimeout = (ms: number) => Math.round(ms * FLOW_TIMEOUT_SCALE)
+
+// the ceiling backing a bounded step must never fire before the step's own
+// deadline. waitFor and extendedWaitUntil scale their declared timeout by
+// SOOTSIM_FLOW_TIMEOUT_SCALE, so the ceiling scales it too.
+function stepCeilingMs(step: MaestroStep): number {
+  const waitForTimeout =
+    typeof step.waitFor?.timeout === 'number' ? step.waitFor.timeout : 0
+  const extendedWaitTimeout =
+    typeof step.extendedWaitUntil?.timeout === 'number'
+      ? step.extendedWaitUntil.timeout
+      : 0
+  return Math.max(
+    60_000,
+    scaledTimeout(waitForTimeout) + 15_000,
+    scaledTimeout(extendedWaitTimeout) + 15_000,
+  )
+}
 type FlowScreenshotPathMode = 'dir' | 'flow'
 type ReplayTapTarget = SootSimReplayTarget
 
@@ -218,23 +256,6 @@ function accessibilityTextMatcher(
   )
 }
 
-// maestro reads ios frames as integer edges (AXElement.boundsString).
-function accessibilityBounds(node: PeachAccessibilityNode): {
-  x: number
-  y: number
-  width: number
-  height: number
-} {
-  const left = Math.trunc(node.frame.x)
-  const top = Math.trunc(node.frame.y)
-  return {
-    x: left,
-    y: top,
-    width: Math.trunc(node.frame.x + node.frame.width) - left,
-    height: Math.trunc(node.frame.y + node.frame.height) - top,
-  }
-}
-
 const ACCESSIBILITY_TRAIT_FILTERS: Record<string, AccessibilityNodePredicate> = {
   // IOSDriver sets attributes["text"] on every node, including empty text.
   TEXT: () => true,
@@ -338,7 +359,12 @@ function distinctAccessibilityNodes(
       node.children.length,
     ])
     const bucket = buckets.get(key)
-    if (bucket?.some((other) => sameNativeAccessibilityShape(node, other))) return false
+    if (
+      bucket?.some((other) =>
+        sameNativeAccessibilityShape(node, other, accessibilityBounds),
+      )
+    )
+      return false
     if (bucket) bucket.push(node)
     else buckets.set(key, [node])
     return true
@@ -354,39 +380,6 @@ function accessibilityAnchorSelector(value: unknown): FlowTargetSelector {
   return isSelectorRecord(value) ? value : {}
 }
 
-// upstream Filters.containsChild compares the resolved child TreeNode against
-// a candidate's immediate children by structural equality: the native
-// attribute map, the boolean flags, and the children, recursively. the native
-// hintText attribute is the placeholder (accessibilityHint is not a TreeNode
-// attribute), and engine identity (elementId/nodeId) plus the projection's own
-// metadata (type, role, isAccessibilityElement, state) are not part of that
-// native shape.
-function sameNativeAccessibilityShape(
-  a: PeachAccessibilityNode,
-  b: PeachAccessibilityNode,
-): boolean {
-  if (
-    (a.testID ?? '') !== (b.testID ?? '') ||
-    (a.label ?? '') !== (b.label ?? '') ||
-    (a.placeholder ?? '') !== (b.placeholder ?? '') ||
-    (a.value ?? '') !== (b.value ?? '') ||
-    a.enabled !== b.enabled ||
-    a.selected !== b.selected ||
-    a.checked !== b.checked ||
-    a.clickable !== b.clickable ||
-    (a.hasFocus ?? false) !== (b.hasFocus ?? false) ||
-    JSON.stringify(accessibilityBounds(a)) !== JSON.stringify(accessibilityBounds(b)) ||
-    a.children.length !== b.children.length
-  ) {
-    return false
-  }
-  for (const [index, child] of a.children.entries()) {
-    const other = b.children[index]
-    if (!other || !sameNativeAccessibilityShape(child, other)) return false
-  }
-  return true
-}
-
 // Filters.containsDescendants: every selector must match inside a child
 // subtree; the node itself is excluded. A selector matches a subtree node by
 // the full filter applied to that single node (Filters' `matches`), which for
@@ -473,7 +466,7 @@ function filterAccessibilityNodesIn(
     candidates = child
       ? candidates.filter((node) =>
           node.children.some((candidate) =>
-            sameNativeAccessibilityShape(candidate, child),
+            sameNativeAccessibilityShape(candidate, child, accessibilityBounds),
           ),
         )
       : []
@@ -662,6 +655,14 @@ export interface MaestroStep {
     optional?: boolean
   }
   waitForAnimationToEnd?: boolean | number | { timeout?: number }
+  advanceAnimationClock?:
+    | number
+    | number[]
+    | {
+        steps?: number | number[]
+        ms?: number | number[]
+        fps?: number
+      }
   back?: boolean
   hideKeyboard?: boolean
   launchApp?: any
@@ -992,6 +993,8 @@ export class SootSimBridgeFlowRunner {
 
   private firstLaunchDone = false
   private appStopped = false
+  private animationClockLocked = false
+  private flowDepth = 0
   private profilingEnabled = false
   private recordingEnabled = false
   private recordingAccessChecked = false
@@ -1884,7 +1887,7 @@ export class SootSimBridgeFlowRunner {
         await this.tap(point.x, point.y, point.target)
         await repeatTaps(tappedAtMs, () => this.tap(point.x, point.y, point.target))
       }
-      await this.settleAfterInput()
+      await this.waitForAppToSettle()
       return
     }
     // auto-wait like real maestro: if the target is not mounted yet, poll
@@ -1938,7 +1941,7 @@ export class SootSimBridgeFlowRunner {
           throw new Error(`tapOn refused: ${JSON.stringify(hit)}`)
         if (hit?.hit === true) {
           await repeatTaps(tappedAtMs, () => this.tap(cx, cy, replayTarget))
-          await this.settleAfterInput()
+          await this.waitForAppToSettle()
           if (!current.isTextInput) return
           // confirm focus landed on THIS text input; retry the tap if a
           // previous field still owns focus.
@@ -1960,7 +1963,7 @@ export class SootSimBridgeFlowRunner {
           )
         : null
     if (direct?.ok) {
-      await this.settleAfterInput()
+      await this.waitForAppToSettle()
       return
     }
     throw new Error(`tapOn: element not found: ${JSON.stringify(opts)}`)
@@ -1974,12 +1977,12 @@ export class SootSimBridgeFlowRunner {
     if (result?.ok === false || result?.value === false) {
       throw new Error(`longPressOn: long press missed: ${JSON.stringify(opts)}`)
     }
-    await this.settleAfterInput()
+    await this.waitForAppToSettle()
   }
 
   async tapAtCoords(x: number, y: number) {
     await this.tap(x, y)
-    await this.settleAfterInput()
+    await this.waitForAppToSettle()
   }
 
   async doubleTapAtCoords(x: number, y: number, gapMs = 80) {
@@ -1991,7 +1994,7 @@ export class SootSimBridgeFlowRunner {
         `doubleTapAtCoords failed at (${x}, ${y}): ${result?.error ?? 'double tap missed'}`,
       )
     }
-    await this.settleAfterInput()
+    await this.waitForAppToSettle()
   }
 
   async assertVisible(target: string | { id?: string; text?: string }) {
@@ -2532,7 +2535,7 @@ export class SootSimBridgeFlowRunner {
     if (!result?.ok) {
       throw new Error(`drag failed: ${result?.error ?? 'drag missed'}`)
     }
-    await this.settleAfterInput()
+    await this.waitForAppToSettle()
   }
 
   async swipeCoords(start: string, end: string, duration = 400) {
@@ -2643,6 +2646,76 @@ export class SootSimBridgeFlowRunner {
     })
   }
 
+  // step peach's lockstep animation clock by one or more explicit millisecond
+  // deltas and hold the clock parked at the final frame so a subsequent
+  // takeScreenshot or assertion reads that exact presentation phase.
+  async advanceAnimationClock(spec: NonNullable<MaestroStep['advanceAnimationClock']>) {
+    const rawSteps =
+      typeof spec === 'number' || Array.isArray(spec) ? spec : (spec.steps ?? spec.ms)
+    const steps = (Array.isArray(rawSteps) ? rawSteps : [rawSteps]).map((value) =>
+      Number(value),
+    )
+    if (steps.length === 0 || steps.some((ms) => !Number.isFinite(ms) || ms <= 0)) {
+      throw new Error(
+        `advanceAnimationClock requires positive millisecond step(s): ${JSON.stringify(spec)}`,
+      )
+    }
+    const fps =
+      typeof spec === 'object' &&
+      !Array.isArray(spec) &&
+      typeof spec.fps === 'number' &&
+      Number.isFinite(spec.fps) &&
+      spec.fps > 0
+        ? spec.fps
+        : 60
+    const result = await this.evaluate<{
+      ok: boolean
+      error?: string
+      virtualTimestampMs?: number
+      frameIndex?: number
+    }>(
+      `(async () => {
+        const lockstep = window.SootSim?.bridges?.lockstepCapture
+        if (!lockstep || typeof lockstep.begin !== 'function') {
+          return { ok: false, error: 'lockstep capture bridge unavailable' }
+        }
+        let controller = window.__peachFlowAnimationClockController
+        if (!controller) {
+          controller = await lockstep.begin(${JSON.stringify(fps)})
+          window.__peachFlowAnimationClockController = controller
+        }
+        let receipt = controller.initialFrame
+        for (const ms of ${JSON.stringify(steps)}) {
+          receipt = await controller.stepFrame(ms)
+        }
+        return {
+          ok: true,
+          virtualTimestampMs: receipt?.virtualTimestampMs,
+          frameIndex: receipt?.frameIndex,
+        }
+      })()`,
+      60_000,
+    )
+    if (!result?.ok) {
+      throw new Error(`advanceAnimationClock failed: ${result?.error ?? 'unknown error'}`)
+    }
+    this.animationClockLocked = true
+  }
+
+  private async releaseAnimationClock() {
+    if (!this.animationClockLocked) return
+    this.animationClockLocked = false
+    await this.evaluate(`(() => {
+      const controller = window.__peachFlowAnimationClockController
+      window.__peachFlowAnimationClockController = null
+      if (controller && typeof controller.end === 'function') {
+        controller.end()
+        return
+      }
+      window.SootSim?.bridges?.lockstepCapture?.end?.()
+    })()`).catch(() => {})
+  }
+
   async back() {
     const dispatched = await this.bridge.send({
       type: 'call',
@@ -2919,14 +2992,8 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
-  // maestro waits around taps for the screen to stop changing, up to
-  // its ios driver's 3 s settle budget, comparing screenshots, so an action
-  // still in flight (a submit spinner, a sheet closing) finishes before the
-  // next command resolves its target. compare consecutive screen pixels,
-  // rather than requiring frame publications to stop for half a second:
-  // a focused input keeps repainting its native blinking caret.
-  // a screen that never stops proceeds when the budget runs out, as there,
-  // and names what kept it moving: every such step pays the whole budget.
+  // ios checks pixels for three seconds, then compares native hierarchies.
+  // the observer overlaps those reads to keep this command's existing budget.
   private async waitForAppToSettle() {
     try {
       const result = await waitForSootsimIdle({
@@ -2934,7 +3001,7 @@ export class SootSimBridgeFlowRunner {
         simId: this.opts.simId,
         maxMs: 3000,
         pollMs: 32,
-        strict: true,
+        maestro: true,
         paintStill: true,
       })
       if (!result.settled) {
@@ -2951,11 +3018,6 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
-  private async settleAfterInput() {
-    await this.waitForAppToSettle()
-    this.lastInteractionAt = Date.now()
-  }
-
   private async waitForVisualSettle() {
     const result = await waitForSootsimIdle({
       bridge: this.bridge,
@@ -2963,19 +3025,10 @@ export class SootSimBridgeFlowRunner {
       maxMs: 10_000,
       pollMs: 32,
       stablePolls: 3,
-      strict: true,
+      maestro: true,
       paintStill: true,
     })
     if (!result.settled) {
-      // an app loop that never ends (a pulsing status dot) leaves only the
-      // pixels moving. maestro on ios captures that frame and continues, so
-      // do the same; any other blocker is real unfinished work and still fails.
-      if (result.blockedBy.startsWith('screen pixels still changing over ')) {
-        console.warn(
-          `  [flow]   screen never became still in ${result.elapsed}ms; capturing as maestro does`,
-        )
-        return
-      }
       throw new Error(
         `visual state did not settle within ${result.elapsed}ms (${result.blockedBy})`,
       )
@@ -3322,6 +3375,10 @@ export class SootSimBridgeFlowRunner {
       }
     }
 
+    // containers run each child through runStep, so every child keeps its own
+    // deadline and failure. the container has no clock of its own: a parent
+    // clock fails the parent while its children are still making progress.
+    const isContainer = !!(step.runFlow || step.repeat || step.retry)
     try {
       // containers defer to their executed children: a nested launch must finish
       // resetting the guest before the first playable frame is recorded.
@@ -3329,9 +3386,7 @@ export class SootSimBridgeFlowRunner {
         this.recordingEnabled &&
         this.recordingStartedAtMs == null &&
         !step.launchApp &&
-        !step.runFlow &&
-        !step.repeat &&
-        !step.retry
+        !isContainer
       ) {
         await this.ensureRecordingStarted()
       }
@@ -3341,7 +3396,8 @@ export class SootSimBridgeFlowRunner {
       startedAtMs = Date.now()
       // simple commands have a wall-clock watchdog. bounded operations keep
       // their own lookup, settle and bridge deadlines, so the watchdog cannot
-      // report a completed step while its action continues in the background.
+      // report a completed step while its action continues in the background;
+      // the step ceiling only backs those deadlines up.
       const hasBoundedWait = !!(
         // taps combine bounded lookup, settling and delivery. a wall-clock
         // watchdog can finish the step while that action is still running.
@@ -3353,14 +3409,6 @@ export class SootSimBridgeFlowRunner {
           step.extendedWaitUntil ||
           step.waitFor ||
           step.scrollUntilVisible ||
-          step.launchApp ||
-          // deep links own the same bounded guest launch and tree waits.
-          step.openLink ||
-          step.runFlow ||
-          // retry reruns its body on failure, so its wall time is the body's
-          // times the retry count — the 10s no-progress watchdog is the wrong
-          // budget and would report "bridge probably hung" for a slow retry.
-          step.retry ||
           // runScript http calls are synchronous with a 5-minute upstream
           // timeout — the 10s watchdog would kill legitimate setup scripts.
           step.runScript ||
@@ -3372,6 +3420,7 @@ export class SootSimBridgeFlowRunner {
           // waitForAnimationToEnd ends at its own timeout, which a flow may set
           // past 10s, and continues as maestro does on a screen still moving.
           step.waitForAnimationToEnd ||
+          step.advanceAnimationClock ||
           // assertions wait out maestro's lookup window, longer than 10s, and
           // every query they make times out on its own, so they report their
           // own failure instead of the watchdog's guess.
@@ -3382,27 +3431,40 @@ export class SootSimBridgeFlowRunner {
       const STEP_WATCHDOG_MS = 10_000
       const body = this.runStepInner(step)
       let screenshotPath: string | undefined
-      if (hasBoundedWait) {
+      // launchApp self-governs with an internal waitForTree (120s on a
+      // clearState reload): a cache-cleared reload of a heavy bundle re-fetches
+      // every chunk from metro and routinely needs more than the step ceiling.
+      // openLink relaunches the guest through the same bounded reload and tree
+      // wait, so it governs itself the same way.
+      if (isContainer || step.launchApp || step.openLink) {
         const result = await body
         if (typeof result === 'string') screenshotPath = result
       } else {
+        const deadlineMs = hasBoundedWait ? stepCeilingMs(step) : STEP_WATCHDOG_MS
         let timer: ReturnType<typeof setTimeout> | null = null
-        const watchdog = new Promise<never>((_, reject) => {
+        const deadline = new Promise<never>((_, reject) => {
           timer = setTimeout(() => {
             reject(
               new Error(
-                `step watchdog: ${stepName} made no progress in ${STEP_WATCHDOG_MS}ms — bridge or bundle probably hung`,
+                hasBoundedWait
+                  ? `step ${stepIndex + 1} (${stepName}) exceeded ${deadlineMs}ms deadline`
+                  : `step watchdog: ${stepName} made no progress in ${STEP_WATCHDOG_MS}ms — bridge or bundle probably hung`,
               ),
             )
-          }, STEP_WATCHDOG_MS)
+          }, deadlineMs)
         })
         try {
-          const result = await Promise.race([body, watchdog])
+          const result = await Promise.race([body, deadline])
           if (typeof result === 'string') screenshotPath = result
         } finally {
           if (timer) clearTimeout(timer)
         }
       }
+      // Orchestra.executeCommand restarts the lookup window after every
+      // command that returns mutating; containers leave it to their children.
+      if (!isContainer && !NON_MUTATING_STEPS.some((key) => step[key] !== undefined)) {
+        this.lastInteractionAt = Date.now()
+      }
       const isAssertion = !!(
         step.assertVisible ||
         step.assertNotVisible ||
@@ -3460,6 +3522,25 @@ export class SootSimBridgeFlowRunner {
   }
 
   private async runStepInner(step: MaestroStep) {
+    if (
+      this.animationClockLocked &&
+      !step.advanceAnimationClock &&
+      !step.takeScreenshot &&
+      !step.assertVisible &&
+      !step.assertNotVisible &&
+      step.assertTrue === undefined &&
+      !step.assertTreeContains &&
+      !step.dumpTree &&
+      step.copyTextFrom === undefined &&
+      typeof step.evalScript !== 'string' &&
+      !step.runScript &&
+      step.setClipboard === undefined &&
+      !step.runFlow &&
+      !step.repeat &&
+      !step.retry
+    ) {
+      await this.releaseAnimationClock()
+    }
     if (step.tapOn) await this.tapOn(step.tapOn)
     else if (step.doubleTapOn) {
       // maestro YamlFluentCommand: doubleTapOn is tapOn with TapRepeat(2, delay)
@@ -3514,6 +3595,8 @@ export class SootSimBridgeFlowRunner {
             ? waitSpec.timeout
             : 2000,
       )
+    } else if (step.advanceAnimationClock !== undefined) {
+      await this.advanceAnimationClock(step.advanceAnimationClock)
     } else if (step.back) {
       await this.back()
     } else if (step.hideKeyboard) {
@@ -3746,67 +3829,54 @@ export class SootSimBridgeFlowRunner {
   async runFlow(steps: (MaestroStep | string)[], options: { skipPlan?: boolean } = {}) {
     const { onStart, onComplete, body } = this.extractFlowBody(steps)
     this.lastInteractionAt = Date.now()
+    this.flowDepth++
 
-    if (!options.skipPlan && this.liveStatus) {
-      await this.planFlow(steps)
-    }
+    try {
+      if (!options.skipPlan && this.liveStatus) {
+        await this.planFlow(steps)
+      }
 
-    if (onStart.length > 0) {
-      console.log(`[flow] onFlowStart (${onStart.length} steps)`)
-      for (let i = 0; i < onStart.length; i++) {
-        await this.runStep(onStart[i], i)
+      if (onStart.length > 0) {
+        console.log(`[flow] onFlowStart (${onStart.length} steps)`)
+        for (let i = 0; i < onStart.length; i++) {
+          await this.runStep(onStart[i], i)
+        }
       }
-    }
 
-    let caughtError: Error | null = null
-    try {
-      await this.runFlowBody(body)
-    } catch (err) {
-      caughtError = err instanceof Error ? err : new Error(String(err))
-    }
+      let caughtError: Error | null = null
+      try {
+        await this.runFlowBody(body)
+      } catch (err) {
+        caughtError = err instanceof Error ? err : new Error(String(err))
+      }
 
-    if (onComplete.length > 0) {
-      console.log(`[flow] onFlowComplete (${onComplete.length} steps)`)
-      for (let i = 0; i < onComplete.length; i++) {
-        try {
-          await this.runStep(onComplete[i], i)
-        } catch (hookErr) {
-          console.warn(
-            `[flow]   onFlowComplete step ${i + 1} failed: ${
-              hookErr instanceof Error ? hookErr.message : hookErr
-            }`,
-          )
+      if (onComplete.length > 0) {
+        console.log(`[flow] onFlowComplete (${onComplete.length} steps)`)
+        for (let i = 0; i < onComplete.length; i++) {
+          try {
+            await this.runStep(onComplete[i], i)
+          } catch (hookErr) {
+            console.warn(
+              `[flow]   onFlowComplete step ${i + 1} failed: ${
+                hookErr instanceof Error ? hookErr.message : hookErr
+              }`,
+            )
+          }
         }
       }
-    }
 
-    if (caughtError) throw caughtError
+      if (caughtError) throw caughtError
+    } finally {
+      this.flowDepth = Math.max(0, this.flowDepth - 1)
+      if (this.flowDepth === 0) {
+        await this.releaseAnimationClock()
+      }
+    }
   }
 
   private async runFlowBody(steps: MaestroStep[]) {
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i]
-      // the ceiling must never fire before the step's own deadline. waitFor and
-      // extendedWaitUntil both scale their declared timeout by
-      // SOOTSIM_FLOW_TIMEOUT_SCALE, so the ceiling scales it too — and it has to
-      // count extendedWaitUntil at all. Missing that, a flow declaring
-      // `extendedWaitUntil: {timeout: 90000}` was killed by the race at 60s while
-      // runStep was still waiting, so runStep never reached its own catch and the
-      // step was never recorded: a failed run whose every recorded step is green.
-      const explicitWait = typeof step.wait === 'number' ? step.wait : 0
-      const waitForTimeout =
-        typeof step.waitFor?.timeout === 'number' ? step.waitFor.timeout : 0
-      const extendedWaitTimeout =
-        typeof step.extendedWaitUntil?.timeout === 'number'
-          ? step.extendedWaitUntil.timeout
-          : 0
-      const stepCeiling = Math.max(
-        60_000,
-        explicitWait + 15_000,
-        scaledTimeout(waitForTimeout) + 15_000,
-        scaledTimeout(extendedWaitTimeout) + 15_000,
-      )
-
       // pause gate + live rail: checked between top-level steps only, so a
       // devtools pause never interrupts a step mid-gesture.
       if (this.liveStatus) {
@@ -3843,34 +3913,11 @@ export class SootSimBridgeFlowRunner {
       }
 
       try {
-        // runFlow runs its own sub-steps (each separately deadlined) and
-        // launchApp self-governs with an internal waitForTree (120s on a
-        // clearState reload) — a cache-cleared reload of a heavy bundle (bluesky)
-        // re-fetches every chunk from metro and routinely needs >60s, so the
-        // outer per-step race would kill a launch that's legitimately still
-        // booting. let both govern their own timing.
-        if (step.runFlow || step.launchApp) {
-          await this.runStep(step, i, onStepStart)
-        } else {
-          await Promise.race([
-            this.runStep(step, i, onStepStart),
-            new Promise<never>((_, reject) =>
-              setTimeout(
-                () =>
-                  reject(
-                    new Error(
-                      `step ${i + 1} (${Object.keys(step)[0]}) exceeded ${stepCeiling}ms deadline`,
-                    ),
-                  ),
-                stepCeiling,
-              ),
-            ),
-          ])
-        }
+        // runStep owns every step's deadline, nested or top level.
+        await this.runStep(step, i, onStepStart)
       } catch (error) {
-        // a ceiling hit rejects the race while runStep is still awaiting, so
-        // runStep never records the step itself. record it here so the trace
-        // always names the step that failed.
+        // a when predicate that throws fails before runStep records the step.
+        // record it here so the trace always names the step that failed.
         const last = this.flowTraceSteps[this.flowTraceSteps.length - 1]
         if (!(last && last.stepIndex === i && last.startedAtMs >= liveStartedAtMs)) {
           const stepName = Object.keys(step)[0]