peachsim 0.1.1594 → 0.1.1619

package/cli/bridge-flow-runner.ts

@@ -1,5 +1,6 @@
 import * as fs from 'fs'
 import * as path from 'path'
+import { isTextInputEditCommand, type TextInputEditCommand } from '@peach/globals'
 import {
   isStorageSnapshot,
   prepareStorageSnapshotForShare,
@@ -36,6 +37,7 @@ import type {
   SystemPermissionKind,
   SystemPermissionStatus,
 } from '@peach/globals'
+import type { ProfileFile } from '@peach/globals/profiler'
 
 const DEFAULT_TIMEOUT = 10000
 // how long maestro looks for a required assertion's element, counted from the
@@ -185,32 +187,35 @@ function accessibilitySubtreeNodes(
 function accessibilityTextMatcher(
   value: string,
   kind: 'text' | 'id',
-): (candidate: string | null) => boolean {
-  // absolute boundaries preserve Regex.matches with multiline enabled, even
-  // for a final newline. ^ and $ inside the user's pattern still match lines.
-  let pattern: RegExp
+): ((candidate: string | null) => boolean) & Pick<RegExp, 'source' | 'flags'> {
+  let source = value
   try {
-    pattern = new RegExp(`(?<![\\s\\S])(?:${value})(?![\\s\\S])`, 'ism')
+    new RegExp(source, 'ism')
   } catch {
     // upstream StringUtils.toRegexSafe quotes an invalid regex as literal copy.
-    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-    pattern = new RegExp(`(?<![\\s\\S])(?:${escaped})(?![\\s\\S])`, 'ism')
+    source = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
   }
-  return (candidate) => {
-    // IOSDriver emits an empty attribute for absent label, value and id.
-    const native = candidate ?? ''
-    if (kind === 'id')
+  // absolute boundaries preserve Regex.matches with multiline enabled, even
+  // for a final newline. ^ and $ inside the user's pattern still match lines.
+  const pattern = new RegExp(`(?<![\\s\\S])(?:${source})(?![\\s\\S])`, 'ism')
+  return Object.assign(
+    (candidate: string | null) => {
+      // IOSDriver emits an empty attribute for absent label, value and id.
+      const native = candidate ?? ''
+      if (kind === 'id')
+        return (
+          pattern.test(native) || pattern.test(native.slice(native.lastIndexOf('/') + 1))
+        )
+      const stripped = native.replaceAll('\n', ' ')
       return (
-        pattern.test(native) || pattern.test(native.slice(native.lastIndexOf('/') + 1))
+        native === value ||
+        stripped === value ||
+        pattern.test(native) ||
+        pattern.test(stripped)
       )
-    const stripped = native.replaceAll('\n', ' ')
-    return (
-      native === value ||
-      stripped === value ||
-      pattern.test(native) ||
-      pattern.test(stripped)
-    )
-  }
+    },
+    { source: pattern.source, flags: pattern.flags },
+  )
 }
 
 // maestro reads ios frames as integer edges (AXElement.boundsString).
@@ -613,6 +618,7 @@ export interface MaestroStep {
         optional?: boolean
       }
   inputText?: string
+  editText?: TextInputEditCommand
   pressKey?: string
   dispatchKey?: string
   swipe?: {
@@ -793,6 +799,27 @@ const MAESTRO_PERMISSION_STATUS: Record<string, SystemPermissionStatus> = {
   unset: 'not-determined',
 }
 
+// maestro's ios location permission also takes the CLAuthorizationStatus names:
+// always is authorized always, inuse is authorized when in use and still
+// undetermined for always, never is denied.
+const MAESTRO_LOCATION_STATUS: Record<
+  string,
+  readonly (readonly [SystemPermissionKind, SystemPermissionStatus])[]
+> = {
+  always: [
+    ['location-when-in-use', 'authorized'],
+    ['location-always', 'authorized'],
+  ],
+  inuse: [
+    ['location-when-in-use', 'authorized'],
+    ['location-always', 'not-determined'],
+  ],
+  never: [
+    ['location-when-in-use', 'denied'],
+    ['location-always', 'denied'],
+  ],
+}
+
 function maestroLaunchPermissions(
   permissions: unknown,
 ): Map<SystemPermissionKind, SystemPermissionStatus> {
@@ -802,12 +829,24 @@ function maestroLaunchPermissions(
   const statuses = new Map<SystemPermissionKind, SystemPermissionStatus>()
   // `all` first so a named permission overrides it
   entries.sort(([a], [b]) => Number(b === 'all') - Number(a === 'all'))
-  for (const [name, value] of entries) {
-    const status = MAESTRO_PERMISSION_STATUS[String(value).toLowerCase()]
+  for (const [name, rawValue] of entries) {
+    const permission = name.toLowerCase()
+    const value = String(rawValue).toLowerCase()
+    const locationStatuses =
+      permission === 'location' ? MAESTRO_LOCATION_STATUS[value] : undefined
+    if (locationStatuses) {
+      for (const [kind, status] of locationStatuses) statuses.set(kind, status)
+      continue
+    }
+    const status = MAESTRO_PERMISSION_STATUS[value]
     if (!status) {
-      throw new Error(`launchApp.permissions.${name} must be allow, deny, or unset`)
+      throw new Error(
+        permission === 'location'
+          ? `launchApp.permissions.${name} must be allow, deny, unset, always, inuse, or never`
+          : `launchApp.permissions.${name} must be allow, deny, or unset`,
+      )
     }
-    for (const kind of MAESTRO_PERMISSION_KINDS[name.toLowerCase()] ?? []) {
+    for (const kind of MAESTRO_PERMISSION_KINDS[permission] ?? []) {
       statuses.set(kind, status)
     }
   }
@@ -933,6 +972,13 @@ export function parseFlowSteps(content: string): MaestroStep[] {
   return parseFlowFile(content).steps
 }
 
+class CaptureSetupError extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause })
+    this.name = 'CaptureSetupError'
+  }
+}
+
 export class SootSimBridgeFlowRunner {
   stepDelay = 0
 
@@ -952,7 +998,7 @@ export class SootSimBridgeFlowRunner {
   private recordingStartedAtMs: number | null = null
   private lastRecordingStartedAtMs: number | null = null
   private lastRecordingDurationMs: number | null = null
-  private lastRecordingFrameStats: unknown = null
+  private lastRecordingProfile: ProfileFile | null = null
   private previewStorageSnapshot: ShareableStorageSnapshot | null = null
   private flowTraceSteps: SootSimFlowTraceStep[] = []
   // when the latest step that acted on the app settled
@@ -1108,7 +1154,17 @@ export class SootSimBridgeFlowRunner {
     throw new Error(`app not ready after ${timeout}ms: ${waitReadyReason(status)}`)
   }
 
+  // capture setup failures are run failures: wrapping them keeps an optional
+  // step or a retry body from consuming them as ordinary action failures.
   private async ensureRecordingStarted() {
+    try {
+      await this.startRecordingOnce()
+    } catch (error) {
+      throw error instanceof CaptureSetupError ? error : new CaptureSetupError(error)
+    }
+  }
+
+  private async startRecordingOnce() {
     if (!this.opts.recordingOutputDir) {
       throw new Error('recording output directory not configured')
     }
@@ -1153,10 +1209,25 @@ export class SootSimBridgeFlowRunner {
       throw new Error(result?.error || 'recording unavailable on this page')
     }
     if (!this.recordingStartedAtMs) {
-      this.recordingStartedAtMs =
+      const startedAtMs =
         typeof result.startedAtMs === 'number' && Number.isFinite(result.startedAtMs)
           ? result.startedAtMs
           : startedAt
+      // events can start before video setup, even without a launchApp step.
+      // rebase once at the shared first-frame boundary for every start path;
+      // the start is ready only after the rebase lands, so a rejected rebase
+      // stops the recorder and leaves no half-started state to skip past.
+      try {
+        await this.evaluate(`(() => {
+          const recorder = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder
+          if (!recorder?.isRecording?.()) return
+          return recorder.markVisibleStart(${JSON.stringify(startedAtMs)})
+        })()`)
+      } catch (error) {
+        await this.evaluate(`window.__sootsimRecorder.stop()`).catch(() => {})
+        throw error
+      }
+      this.recordingStartedAtMs = startedAtMs
     }
   }
 
@@ -1177,8 +1248,8 @@ export class SootSimBridgeFlowRunner {
     return this.lastRecordingStartedAtMs
   }
 
-  getLastRecordingFrameStats(): unknown {
-    return this.lastRecordingFrameStats
+  getLastRecordingProfile(): ProfileFile | null {
+    return this.lastRecordingProfile
   }
 
   getPreviewStorageSnapshot(): ShareableStorageSnapshot | null {
@@ -1257,7 +1328,7 @@ export class SootSimBridgeFlowRunner {
     if (this.recordingStartedAtMs == null) {
       this.lastRecordingStartedAtMs = null
       this.lastRecordingDurationMs = null
-      this.lastRecordingFrameStats = null
+      this.lastRecordingProfile = null
       return null
     }
 
@@ -1267,11 +1338,11 @@ export class SootSimBridgeFlowRunner {
       size?: number
       mime?: string
       durationMs: number
-      frameStats?: unknown
+      profile?: ProfileFile | null
     }>(`window.__sootsimRecorder.stop()`)
     if (!stopped?.ok) {
       this.recordingStartedAtMs = null
-      this.lastRecordingFrameStats = null
+      this.lastRecordingProfile = null
       throw new Error(stopped?.error || 'recording stop failed')
     }
     if (!Number.isFinite(stopped.durationMs) || stopped.durationMs <= 0) {
@@ -1279,7 +1350,7 @@ export class SootSimBridgeFlowRunner {
     }
     this.lastRecordingStartedAtMs = this.recordingStartedAtMs
     this.lastRecordingDurationMs = stopped.durationMs
-    this.lastRecordingFrameStats = stopped.frameStats ?? null
+    this.lastRecordingProfile = stopped.profile ?? null
     this.recordingStartedAtMs = null
 
     // drain blob in chunks
@@ -1425,7 +1496,16 @@ export class SootSimBridgeFlowRunner {
       if (!test || !test.queryAll) return null
       const selector = ${JSON.stringify(opts)}
       const compile = ${accessibilityTextMatcher.toString()}
-      const all = ((await test.queryAll({})) || []).filter(
+      // relative filters need their anchors too; other id selectors only
+      // project matching nodes, retaining every duplicate for ordering below.
+      // patterns accepting an absent id also need unidentified nodes.
+      const idMatcher = selector.id == null ? null : compile(selector.id, 'id')
+      const needsAnchors = ['childOf', 'below', 'above', 'leftOf', 'rightOf']
+        .some((key) => selector[key] != null)
+      const query = idMatcher && !idMatcher(null) && !needsAnchors
+        ? { idPattern: { source: idMatcher.source, flags: idMatcher.flags, matchLastSegment: true } }
+        : {}
+      const all = ((await test.queryAll(query)) || []).filter(
         (n) => n && n.absolutePosition && n.layout,
       )
       // maestro reads ios frames as integer edges (AXElement.boundsString)
@@ -1668,11 +1748,22 @@ export class SootSimBridgeFlowRunner {
     })) as { ok?: boolean; value?: boolean } | null
   }
 
+  // the engine's inspect geometry revision: equal readings bracket a span in
+  // which no tree, layout, scroll or prop write could move any element.
+  private async geometryRevision(): Promise<string | null> {
+    const revision = await this.evaluate(
+      `(async () => window.__sootsimTest?.getGeometryRevision?.())()`,
+    )
+    return typeof revision === 'string' ? revision : null
+  }
+
   private async waitForElement(opts: FlowTargetSelector, timeoutMs = 5000) {
     const deadline = Date.now() + timeoutMs
+    let revision = await this.geometryRevision()
     let element = await this.findElement(opts)
     while (!element && Date.now() < deadline) {
       await sleep(150)
+      revision = await this.geometryRevision()
       element = await this.findElement(opts)
     }
     if (!element) return element
@@ -1682,10 +1773,15 @@ export class SootSimBridgeFlowRunner {
     // new-thread title tap opened the photo picker this way (2026-07-10).
     // require two consecutive samples at the same absolute position before
     // interacting, bounded so a perpetually-animating target still proceeds.
+    // a revision unchanged since the last sample began proves the next
+    // sample would read the same frame, so it is not read again.
     const stabilityDeadline = Date.now() + 1200
     let prev = element
-    while (Date.now() < stabilityDeadline) {
+    do {
       await sleep(120)
+      const sampled = await this.geometryRevision()
+      if (sampled !== null && sampled === revision) return element
+      revision = sampled
       const next = await this.findElement(opts)
       if (!next) break
       const moved =
@@ -1696,7 +1792,7 @@ export class SootSimBridgeFlowRunner {
       element = next
       if (!moved) return element
       prev = next
-    }
+    } while (Date.now() < stabilityDeadline)
     return element
   }
 
@@ -1998,6 +2094,19 @@ export class SootSimBridgeFlowRunner {
     await sleep(200)
   }
 
+  async editText(command: TextInputEditCommand) {
+    if (!isTextInputEditCommand(command))
+      throw new Error('editText: invalid range command')
+    if (!(await this.waitForFocusedTextInput()))
+      throw new Error('editText: no focused TextInput')
+    await this.bridge.send({
+      type: 'keyboard',
+      simId: this.opts.simId,
+      action: 'edit',
+      edit: command,
+    })
+  }
+
   // poll for a focused text input. returns true once getFocusedNode reports a
   // node (focus landed), false if the budget elapses. callers use it both as a
   // tap-focus confirmation (tapOn retry) and a pre-type barrier (inputText).
@@ -2031,7 +2140,7 @@ export class SootSimBridgeFlowRunner {
     expected?: FocusedTextInputInfo | null,
   ): Promise<boolean> {
     const deadline = Date.now() + timeoutMs
-    while (Date.now() < deadline) {
+    do {
       try {
         const focused = await this.callTest<FocusedTextInputInfo | null>('getFocusedNode')
         if (focused && this.focusedTextInputMatches(focused, expected)) return true
@@ -2039,7 +2148,7 @@ export class SootSimBridgeFlowRunner {
         // bridge hiccup — keep polling within the budget
       }
       await sleep(50)
-    }
+    } while (Date.now() < deadline)
     return false
   }
 
@@ -2082,7 +2191,7 @@ export class SootSimBridgeFlowRunner {
     })
 
     const deadline = Date.now() + 3000
-    while (Date.now() < deadline) {
+    do {
       // the host test bridge proxies the tenant, so isTextInputFocused
       // resolves a promise; reading it unawaited is always truthy.
       const state = await this.evaluate<{
@@ -2104,7 +2213,7 @@ export class SootSimBridgeFlowRunner {
         return
       }
       await sleep(80)
-    }
+    } while (Date.now() < deadline)
   }
 
   async eraseText(count: number) {
@@ -2124,11 +2233,11 @@ export class SootSimBridgeFlowRunner {
   async waitFor(opts: { text?: string; id?: string; timeout?: number }) {
     const { timeout, ...selector } = opts
     const deadline = Date.now() + scaledTimeout(timeout || DEFAULT_TIMEOUT)
-    while (Date.now() < deadline) {
+    do {
       const element = await this.findElement(selector)
       if (element) return
       await sleep(200)
-    }
+    } while (Date.now() < deadline)
     // surface whether the element existed but was off-screen vs never
     // showed up at all — the two failure modes need different debugging
     // (scroll-position bug vs missing wait-step / wrong screen).
@@ -2569,7 +2678,7 @@ export class SootSimBridgeFlowRunner {
     )
     const deadline = Date.now() + (opts.timeout || 20000)
     const direction = opts.direction?.toUpperCase() || 'DOWN'
-    while (Date.now() < deadline) {
+    do {
       const screen = await this.screenBounds()
       const centerX = screen.width / 2
       const centerY = screen.height / 2
@@ -2608,7 +2717,7 @@ export class SootSimBridgeFlowRunner {
         Math.max(1, Math.round(duration / 16)),
         16,
       )
-    }
+    } while (Date.now() < deadline)
 
     throw new Error(`scrollUntilVisible: ${JSON.stringify(target)} not found`)
   }
@@ -2619,7 +2728,8 @@ export class SootSimBridgeFlowRunner {
     timeout?: number
   }) {
     const deadline = Date.now() + scaledTimeout(opts.timeout || DEFAULT_TIMEOUT)
-    while (Date.now() < deadline) {
+    // sample once even when scheduling consumes the initial lookup window.
+    do {
       const visibleOkay = opts.visible
         ? await this.isElementVisible(
             typeof opts.visible === 'string' ? { text: opts.visible } : opts.visible,
@@ -2634,7 +2744,7 @@ export class SootSimBridgeFlowRunner {
         : true
       if (visibleOkay && notVisibleOkay) return
       await sleep(200)
-    }
+    } while (Date.now() < deadline)
     throw new Error('extendedWaitUntil timed out')
   }
 
@@ -2679,7 +2789,7 @@ export class SootSimBridgeFlowRunner {
     if (!this.recordingEnabled && !this.profilingEnabled) return
     const deadline = Date.now() + 10000
     let lastError: unknown = null
-    while (Date.now() < deadline) {
+    do {
       try {
         if (this.recordingEnabled) await this.ensureRecordingStarted()
         if (this.profilingEnabled) await this.startProfile()
@@ -2688,7 +2798,7 @@ export class SootSimBridgeFlowRunner {
         lastError = err
         await sleep(250)
       }
-    }
+    } while (Date.now() < deadline)
     throw new Error(
       `capture re-arm failed after app reload: ${
         lastError instanceof Error ? lastError.message : String(lastError)
@@ -2793,17 +2903,7 @@ export class SootSimBridgeFlowRunner {
       // begin its pixels only after launch has mounted and settled, leaving the
       // loading prelude outside the playable video while its trace stays visible.
       await this.waitForVisualSettle()
-      const videoAlreadyStarted = this.recordingStartedAtMs != null
       await this.ensureRecordingStarted()
-      if (!videoAlreadyStarted && this.recordingStartedAtMs != null) {
-        // the preview event recorder has been running since before launch,
-        // so its clock includes the boot prelude the video just skipped.
-        // rebase it to the video's first frame — without this every event
-        // timestamp overshoots the playable video and preview playback can
-        // never align (play stuck disabled). no-op unless the preview
-        // event recorder is running.
-        await this.rebaseEventRecorderToVideoStart(this.recordingStartedAtMs)
-      }
     }
   }
 
@@ -2819,22 +2919,6 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
-  private async rebaseEventRecorderToVideoStart(videoStartedAtMs: number) {
-    try {
-      await this.evaluate(
-        `(() => {
-          const recorder = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder
-          if (!recorder?.isRecording?.()) return 'not-recording'
-          return recorder.markVisibleStart?.(${JSON.stringify(videoStartedAtMs)}) ?? 'no-mark'
-        })()`,
-      )
-    } catch (err) {
-      console.warn(
-        `  warn: event-recorder rebase to video start failed: ${err instanceof Error ? err.message : err}`,
-      )
-    }
-  }
-
   // 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
@@ -2883,6 +2967,15 @@ export class SootSimBridgeFlowRunner {
       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})`,
       )
@@ -2901,7 +2994,7 @@ export class SootSimBridgeFlowRunner {
   private async waitForShellAppLaunched(appId: string, timeoutMs: number) {
     const deadline = Date.now() + timeoutMs
     let lastState: ShellState | null = null
-    while (Date.now() < deadline) {
+    do {
       try {
         lastState = await getShellState(this.bridge)
       } catch {
@@ -2917,7 +3010,7 @@ export class SootSimBridgeFlowRunner {
         return
       }
       await sleep(16)
-    }
+    } while (Date.now() < deadline)
   }
 
   private async launchShellAppFromHomeIfNeeded(opts: unknown): Promise<boolean> {
@@ -3152,7 +3245,11 @@ export class SootSimBridgeFlowRunner {
     )
   }
 
-  async runStep(rawStepInput: MaestroStep | string, stepIndex: number) {
+  async runStep(
+    rawStepInput: MaestroStep | string,
+    stepIndex: number,
+    onStepStart?: () => Promise<void>,
+  ) {
     await this.liveStatus?.waitWhilePaused()
     // maestro allows several commands in BARE-STRING form (`- back`,
     // `- hideKeyboard`, `- waitForAnimationToEnd`, `- scrollUp`, …). yaml parses
@@ -3166,7 +3263,7 @@ export class SootSimBridgeFlowRunner {
     const stepName =
       Object.keys(rawStep).find((k) => k !== 'when') || Object.keys(rawStep)[0]
     console.log(`[flow] step ${stepIndex + 1}: ${stepName}`)
-    const startedAtMs = Date.now()
+    let startedAtMs = Date.now()
     let targetLabel = this.flowStepTargetLabel(rawStep, stepName)
 
     let step: MaestroStep
@@ -3238,6 +3335,10 @@ export class SootSimBridgeFlowRunner {
       ) {
         await this.ensureRecordingStarted()
       }
+      // recording is run setup. neither clock starts until its first frame and
+      // storage capture are ready; the run total still includes that setup.
+      await onStepStart?.()
+      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.
@@ -3327,7 +3428,7 @@ export class SootSimBridgeFlowRunner {
         screenshotPath,
       })
     } catch (error) {
-      if (this.isOptional(step)) {
+      if (!(error instanceof CaptureSetupError) && this.isOptional(step)) {
         console.log(
           `[flow]   (optional, skipped: ${(error as Error).message.slice(0, 80)})`,
         )
@@ -3374,6 +3475,7 @@ export class SootSimBridgeFlowRunner {
     else if (step.assertVisible) await this.assertVisible(step.assertVisible)
     else if (step.assertNotVisible) await this.assertNotVisible(step.assertNotVisible)
     else if (step.inputText) await this.inputText(step.inputText)
+    else if (step.editText) await this.editText(step.editText)
     else if (step.pressKey) await this.pressKey(step.pressKey)
     else if (step.dispatchKey) await this.dispatchKey(step.dispatchKey)
     else if (step.waitFor) await this.waitFor(step.waitFor)
@@ -3490,7 +3592,7 @@ export class SootSimBridgeFlowRunner {
           }
           break
         } catch (error) {
-          if (attempt >= maxRetries) throw error
+          if (error instanceof CaptureSetupError || attempt >= maxRetries) throw error
           console.log(
             `[flow]   retry ${attempt + 1}/${maxRetries} after: ${(error as Error).message.slice(0, 120)}`,
           )
@@ -3709,9 +3811,12 @@ export class SootSimBridgeFlowRunner {
       // devtools pause never interrupts a step mid-gesture.
       if (this.liveStatus) {
         await this.liveStatus.waitWhilePaused()
-        await this.liveStatus.step(i, 'running')
       }
-      const liveStartedAtMs = Date.now()
+      let liveStartedAtMs = Date.now()
+      const onStepStart = async () => {
+        await this.liveStatus?.step(i, 'running')
+        liveStartedAtMs = Date.now()
+      }
       const reportOutcome = async (failed: boolean, error?: unknown) => {
         if (!this.liveStatus) return
         // the last trace entry after runStep settles is the top-level step's
@@ -3727,7 +3832,7 @@ export class SootSimBridgeFlowRunner {
               ? 'skipped'
               : 'success',
           {
-            durationMs: Date.now() - liveStartedAtMs,
+            durationMs: traced ? last.durationMs : Date.now() - liveStartedAtMs,
             error: failed
               ? error instanceof Error
                 ? error.message.slice(0, 300)
@@ -3745,10 +3850,10 @@ export class SootSimBridgeFlowRunner {
         // 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)
+          await this.runStep(step, i, onStepStart)
         } else {
           await Promise.race([
-            this.runStep(step, i),
+            this.runStep(step, i, onStepStart),
             new Promise<never>((_, reject) =>
               setTimeout(
                 () =>