peachsim 0.1.1594 → 0.1.1620

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
@@ -43,6 +45,23 @@ const DEFAULT_TIMEOUT = 10000
 const ASSERTION_LOOKUP_MS = 17_000
 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
 
@@ -185,32 +204,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 +635,7 @@ export interface MaestroStep {
         optional?: boolean
       }
   inputText?: string
+  editText?: TextInputEditCommand
   pressKey?: string
   dispatchKey?: string
   swipe?: {
@@ -793,6 +816,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 +846,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 +989,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 +1015,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 +1171,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 +1226,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 +1265,8 @@ export class SootSimBridgeFlowRunner {
     return this.lastRecordingStartedAtMs
   }
 
-  getLastRecordingFrameStats(): unknown {
-    return this.lastRecordingFrameStats
+  getLastRecordingProfile(): ProfileFile | null {
+    return this.lastRecordingProfile
   }
 
   getPreviewStorageSnapshot(): ShareableStorageSnapshot | null {
@@ -1257,7 +1345,7 @@ export class SootSimBridgeFlowRunner {
     if (this.recordingStartedAtMs == null) {
       this.lastRecordingStartedAtMs = null
       this.lastRecordingDurationMs = null
-      this.lastRecordingFrameStats = null
+      this.lastRecordingProfile = null
       return null
     }
 
@@ -1267,11 +1355,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 +1367,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 +1513,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 +1765,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 +1790,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 +1809,7 @@ export class SootSimBridgeFlowRunner {
       element = next
       if (!moved) return element
       prev = next
-    }
+    } while (Date.now() < stabilityDeadline)
     return element
   }
 
@@ -1998,6 +2111,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 +2157,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 +2165,7 @@ export class SootSimBridgeFlowRunner {
         // bridge hiccup — keep polling within the budget
       }
       await sleep(50)
-    }
+    } while (Date.now() < deadline)
     return false
   }
 
@@ -2082,7 +2208,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 +2230,7 @@ export class SootSimBridgeFlowRunner {
         return
       }
       await sleep(80)
-    }
+    } while (Date.now() < deadline)
   }
 
   async eraseText(count: number) {
@@ -2124,11 +2250,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 +2695,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 +2734,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 +2745,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 +2761,7 @@ export class SootSimBridgeFlowRunner {
         : true
       if (visibleOkay && notVisibleOkay) return
       await sleep(200)
-    }
+    } while (Date.now() < deadline)
     throw new Error('extendedWaitUntil timed out')
   }
 
@@ -2679,7 +2806,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 +2815,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 +2920,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 +2936,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 +2984,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 +3011,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 +3027,7 @@ export class SootSimBridgeFlowRunner {
         return
       }
       await sleep(16)
-    }
+    } while (Date.now() < deadline)
   }
 
   private async launchShellAppFromHomeIfNeeded(opts: unknown): Promise<boolean> {
@@ -3152,7 +3262,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 +3280,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
@@ -3225,6 +3339,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.
@@ -3232,15 +3350,18 @@ export class SootSimBridgeFlowRunner {
         this.recordingEnabled &&
         this.recordingStartedAtMs == null &&
         !step.launchApp &&
-        !step.runFlow &&
-        !step.repeat &&
-        !step.retry
+        !isContainer
       ) {
         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.
+      // 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.
@@ -3252,14 +3373,8 @@ 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 ||
@@ -3281,22 +3396,28 @@ 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.
+      if (isContainer || step.launchApp) {
         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)
@@ -3327,7 +3448,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 +3495,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 +3612,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)}`,
           )
@@ -3684,34 +3806,16 @@ export class SootSimBridgeFlowRunner {
   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) {
         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 +3831,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)
@@ -3738,34 +3842,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)
-        } else {
-          await Promise.race([
-            this.runStep(step, i),
-            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]