rnxsim 0.1.313 → 0.1.314

package/cli/commands/flow.ts

@@ -0,0 +1,1124 @@
+// shared Maestro YAML playback and live-authoring implementation.
+// discovers a sootsim target when needed, then reuses the shared bridge action layer
+
+import * as fs from 'fs'
+import { createHash, randomUUID } from 'node:crypto'
+import { tmpdir } from 'os'
+import * as path from 'path'
+import { scanDevServers } from '../../scripts/dev-server-scanner'
+import { loadOptionalDemoApps } from '../../scripts/optional-demo-registry'
+import { printBridgeFailureDiagnostics } from '../bridge-diagnostics'
+import {
+  SootSimBridgeFlowRunner,
+  type SootSimFlowProfileResult,
+  type SootSimFlowTraceStep,
+} from '../bridge-flow-runner'
+import { readCurrentSimId, saveCurrentSimId } from '../current-sim'
+import { findDesktopCompanion } from '../desktop-companion'
+import { parseFlowFile, validateFlowFile } from '../flow-file'
+import { FlowLiveStatusReporter } from '../flow-live-status'
+import {
+  exportFlowSession,
+  finalizeFlowSession,
+  keepFlowCandidate,
+  startFlowSession,
+} from '../flow-session'
+import { flushCliTelemetry, trackCliEvent } from '../telemetry'
+import { createBridge, createBridgeFromParsed, parseBridgeCliArgs } from '../ws-bridge'
+import {
+  buildShellUrl,
+  closeSimsBulk,
+  resolveShellBaseUrlForBridgePort,
+  runOpenCommand,
+  terminatePlaywrightHostsForSims,
+} from './control'
+import { printShellPerfReport } from './inspect'
+import { resolveDefaultUploadOrigin } from './upload'
+import type { UploadResult } from './upload'
+
+export { parseFlowFile, validateFlowFile } from '../flow-file'
+
+let lastPreviewUploadResult: UploadResult | null = null
+
+export function getLastFlowPreviewUploadResult(): UploadResult | null {
+  return lastPreviewUploadResult
+}
+
+// per-step trace of the most recent playback, preview or not — callers
+// Maestro callers fold this into their run registration.
+let lastFlowTraceSteps: SootSimFlowTraceStep[] = []
+
+export function getLastFlowTraceSteps(): SootSimFlowTraceStep[] {
+  return lastFlowTraceSteps
+}
+
+// resolve a frontmatter `app:` value that may be a port, a URL, or a
+// registered demo name (`bluesky`, `3pc`, `uniswap`, …). returns the
+// raw string for ports/URLs untouched; for a registered name, returns
+// the launcher's preferredPort.
+async function resolveAppFrontmatterTarget(raw: string): Promise<string> {
+  if (!raw) return ''
+  const trimmed = raw.trim()
+  if (!trimmed) return ''
+  if (/^\d+$/.test(trimmed)) return trimmed
+  if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) return trimmed
+  // try a case-insensitive name match against the OPTIONAL internal demo
+  // registry (in-repo only; empty on a published install). unknown strings
+  // fall through unchanged so other targets (host:port, raw bundle URLs
+  // without a scheme) still reach the legacy resolver.
+  const apps = await loadOptionalDemoApps()
+  const match = apps.find((app) => app.name.toLowerCase() === trimmed.toLowerCase())
+  if (match) return String(match.preferredPort)
+  return trimmed
+}
+
+// discover a sootsim shell URL — prefer patched servers, fall back to any match.
+// exported so `detox.ts` and `maestro.ts` can reuse the same discovery logic.
+export async function discoverSootsimUrl(): Promise<string | null> {
+  const servers = await scanDevServers()
+  const patched = servers.find((s) => s.patched)
+  if (patched) return `http://localhost:${patched.port}/__soot/`
+  const any = servers[0]
+  if (any) return `http://localhost:${any.port}/__soot/`
+  return null
+}
+
+export async function runFlowPlayback(args: string[]): Promise<number> {
+  lastPreviewUploadResult = null
+  lastFlowTraceSteps = []
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(`
+sootsim maestro — author and run Maestro YAML flows
+
+usage:
+  sootsim maestro test <flow.yaml> [options]
+  sootsim maestro start
+  sootsim maestro keep
+  sootsim maestro end [--output <path>] [--validate] [--video]
+  sootsim maestro validate <path>
+
+options:
+  --record             record a webm artifact while the flow runs
+  --profile            capture perf stats while the flow runs
+  --out <dir>          output directory (default: /tmp/sootsim-recordings)
+  --device <model>     override the flow frontmatter device for this run
+  --slow <ms>          delay between steps for natural pacing
+  --tail-wait <ms>     hold the recording open after the last step so the
+                       final UI state is captured (default: smart idle up to
+                       6000ms for --preview, fixed 2000ms for --record, 0 otherwise)
+  --url <url>          load this target before running the flow
+  --screenshot-paths <mode>
+                       screenshot path mode: dir (default) or flow
+  --no-shell           capture every screenshot tenant-only (no status bar,
+                       keyboard, notification center, or other shell overlays).
+                       use for clean demo asset sets. per-step \`layers:\`
+                       still wins over this default.
+  --shell-only         inverse — capture shell chrome only
+  --replace <m>=<f>    replace a Metro module with a local file for this run
+  --new                open a fresh sim before running the flow
+  --driver <id>        when paired with --new, use playwright or electron;
+                       browser sims default to isolated playwright
+  --headless           pass headless=true to the launch driver (useful
+                       with --driver playwright)
+  --headed             force a fresh, VISIBLE window for this run (implies
+                       --new; overrides --headless). use when you want to
+                       watch the flow run live even if the current sim is
+                       headless or stale
+  --electron           prefer opening the target in the desktop companion
+  --sim <id>           target a specific current sim
+  --validate           replay the drafted flow before clearing it
+  --video              replay and record the drafted flow before clearing it
+  --preview            record events+video, upload, and print /preview/<id>
+  --preview-open       open the uploaded preview link after a successful run
+  --preview-origin <url>
+                       upload target for --preview (default: auto)
+  --preview-public-origin <url>
+                       public link origin for --preview (default: sootsim.com
+                       for prod uploads)
+  --billing-kind test_run
+                       meter the chained preview upload as a test run
+  --owner <org>        associate preview upload with a linked org repo
+  --repo <repo>        repo name for --owner; user must belong to the team
+
+frontmatter (top of flow.yaml between --- markers):
+  app: 8081            load this target before the flow starts
+  device: iphone-14    set the live device model for this flow run
+  electron: true       prefer the desktop companion sim for this flow
+
+default runtime:
+  bridge-backed flow playback against the current sim
+  if no current sim exists, flow opens the discovered target first
+  recording and profiling both run on the same bridge-backed path
+
+examples:
+  sootsim maestro test login.yaml
+  sootsim maestro test demo.yaml --url 8081 --record --slow 500 --out ./recordings
+  sootsim maestro test demo.yaml --sim a2
+  sootsim maestro start
+  sootsim maestro keep
+  sootsim maestro end --output ./.maestro/draft.yaml
+  sootsim maestro end --output ./.maestro/draft.yaml --validate
+  sootsim maestro end --output ./.maestro/draft.yaml --video
+  sootsim maestro validate ./.maestro/draft.yaml
+
+flow extension:
+  takeScreenshot: hero
+  takeScreenshot:
+    path: marketing/hero
+    withFrame: true
+`)
+    process.exit(0)
+  }
+
+  const flowPath = args[0]
+  if (!fs.existsSync(flowPath)) {
+    console.error(`  error: ${flowPath} not found`)
+    process.exit(1)
+  }
+
+  const getFlag = (name: string) => args.find((_, i) => args[i - 1] === name)
+  const profile = args.includes('--profile')
+  // --headed forces a fresh visible window: implies --new and overrides
+  // --headless (you asked to watch it run).
+  const headed = args.includes('--headed')
+  const openInNewSim = args.includes('--new') || headed
+  const outDir = getFlag('--out') || '/tmp/sootsim-recordings'
+  // when --screenshots isn't explicitly set, default to the --out directory.
+  // this matches what most users expect: one flag controls the whole output
+  // bundle (recording + screenshots) for a demo run.
+  // previously, screenshots silently landed in /tmp/sootsim-flow even when
+  // --out was set, requiring a second --screenshots flag to redirect them.
+  const screenshotDir =
+    getFlag('--screenshots') || (getFlag('--out') ? outDir : '/tmp/sootsim-flow')
+  const screenshotPathMode =
+    getFlag('--screenshot-paths') === 'flow' ? 'flow' : ('dir' as const)
+  // --no-shell makes every takeScreenshot in the flow capture tenant-only
+  // (no status bar, keyboard, notification center). useful for demo asset
+  // sets where shell chrome would obscure the app or stale overlays would
+  // pollute the result. per-step `layers:` still wins over this default.
+  const screenshotLayers: 'full' | 'tenant' | 'shell' | undefined = args.includes(
+    '--no-shell',
+  )
+    ? 'tenant'
+    : args.includes('--shell-only')
+      ? 'shell'
+      : undefined
+  const deviceOverride = getFlag('--device')?.trim() || ''
+  const slow = args.includes('--slow') ? +(getFlag('--slow') || '500') : 0
+  const cliElectron = args.includes('--electron')
+  const preview = args.includes('--preview')
+  // only --preview reads this (start event, entitlement origin, uploader).
+  // resolving it unconditionally probed https://contrast.localhost:3000 and
+  // charged every non-preview flow the probe's full 2s timeout whenever no
+  // local Contrast stack was listening.
+  const previewOrigin = preview
+    ? await resolveDefaultUploadOrigin(getFlag('--preview-origin'))
+    : ''
+  const previewPublicOrigin = getFlag('--preview-public-origin')
+  const previewOpen = args.includes('--preview-open')
+  const previewOwner = getFlag('--owner')?.trim() || ''
+  const previewRepo = getFlag('--repo')?.trim() || ''
+  const previewBillingKind = getFlag('--billing-kind')?.trim() || ''
+  const previewRunScope = preview
+    ? `maestro:${
+        process.env.GITHUB_RUN_ID
+          ? `github:${process.env.GITHUB_RUN_ID}:attempt:${process.env.GITHUB_RUN_ATTEMPT || '1'}:job:${process.env.GITHUB_JOB || 'preview'}`
+          : `local:${randomUUID()}`
+      }:flow:${createHash('sha256')
+        .update(path.relative(process.cwd(), path.resolve(flowPath)))
+        .digest('hex')
+        .slice(0, 16)}`
+    : ''
+  if (previewBillingKind && previewBillingKind !== 'test_run') {
+    console.error(`  error: invalid --billing-kind: ${previewBillingKind}`)
+    process.exit(1)
+  }
+  const replaceArgs = args.flatMap((arg, index) =>
+    args[index - 1] === '--replace' ? ['--replace', arg] : [],
+  )
+  // forward --remap <host:port>=<host:port> to the open command so the sim
+  // boots with the guest-fetch network remap (config.network.remap).
+  const remapArgs = args.flatMap((arg, index) =>
+    args[index - 1] === '--remap' ? ['--remap', arg] : [],
+  )
+  // --preview implies --record: the preview page layers the mp4 over
+  // the canvas during scrub so the viewer sees smooth motion while the
+  // real app is catching up. upload chains the video in automatically.
+  const record = args.includes('--record') || preview
+  // hold the final UI state in the recording so viewers see the result
+  // of the flow, not just a frame mid-transition. short flows otherwise
+  // cut off ~600ms in. caller can override with --tail-wait <ms>.
+  const tailWaitMs = args.includes('--tail-wait')
+    ? Math.max(0, +(getFlag('--tail-wait') || '2000'))
+    : record
+      ? preview
+        ? 6000
+        : 2000
+      : 0
+
+  // parse flow file (frontmatter + steps). `${...}` templates stay verbatim
+  // here — the runner interpolates per step at execution time.
+  const flowContent = fs.readFileSync(flowPath, 'utf8')
+  const { frontmatter, steps } = parseFlowFile(flowContent)
+  if (steps.length === 0) {
+    console.error('  error: flow file must contain a YAML array of steps')
+    process.exit(1)
+  }
+  const targetDevice = deviceOverride || frontmatter.device || ''
+  const targetTheme = frontmatter.theme || ''
+
+  const wantElectron = cliElectron || frontmatter.electron === true
+  const rawTargetApp =
+    frontmatter.app === undefined || frontmatter.app === null
+      ? ''
+      : typeof frontmatter.app === 'number'
+        ? String(frontmatter.app)
+        : frontmatter.app
+  // accept `app: <demo-name>` (e.g. `app: 3pc`) in addition to ports/URLs.
+  // resolve via APPS — the launcher's preferredPort is the explicit target.
+  const targetApp = await resolveAppFrontmatterTarget(rawTargetApp)
+
+  const bridgeArgOptions = {
+    stripBooleanFlags: [
+      '--record',
+      '--profile',
+      '--electron',
+      '--new',
+      '--preview',
+      '--preview-open',
+      '--headless',
+      '--headed',
+    ],
+    stripValueFlags: [
+      '--out',
+      '--device',
+      '--slow',
+      '--tail-wait',
+      '--url',
+      '--replace',
+      '--remap',
+      '--screenshots',
+      '--screenshot-paths',
+      '--preview-origin',
+      '--preview-public-origin',
+      '--driver',
+      '--billing-kind',
+      '--owner',
+      '--repo',
+    ],
+  }
+  const parsedBridgeArgs = parseBridgeCliArgs(args, bridgeArgOptions)
+  const url = getFlag('--url') || ''
+  if (wantElectron && !findDesktopCompanion()) {
+    console.error(
+      '  error: desktop companion not found. install or build it first with `bun run build:electron`',
+    )
+    process.exit(1)
+  }
+
+  const mode = wantElectron ? 'desktop companion' : 'bridge'
+  const appLabel = targetApp ? ` | target: ${targetApp}` : ''
+  console.log(`
+  sootsim maestro — ${path.basename(flowPath)}
+  ${steps.length} steps | ${mode}${appLabel}${record ? ' | recording' : ''}${profile ? ' | profiling' : ''}${slow ? ` | ${slow}ms delay` : ''}
+`)
+
+  // only meter flows that will result in a cloud preview upload. plain
+  // flow playback + local recording stay completely unmetered per the
+  // free/pro/enterprise beta plan (local usage is free). server emits
+  // the authoritative preview_upload events when the chained upload
+  // actually lands.
+  if (preview) {
+    trackCliEvent({
+      event: 'preview_flow_started',
+      properties: {
+        flowName: path.basename(flowPath),
+        stepCount: steps.length,
+        mode,
+        electron: wantElectron,
+        record,
+        profile,
+        previewOrigin,
+      },
+    })
+  }
+
+  let openTarget = url || targetApp || ''
+  const effectiveOpenInNewSim =
+    openInNewSim || (wantElectron && parsedBridgeArgs.simIdSource !== 'flag')
+  const driverFlag = getFlag('--driver') || ''
+  let closeManagedDriverSimAfterRun = false
+  const ownedSimIds = new Set<string>()
+
+  // if we weren't told exactly where to go, and there's already a primary
+  // open tab, just reuse it. opening a fresh tab that auto-discovers some
+  // other dev server on the host is almost never what the user wants — they
+  // already pointed the current tab at the app they want to drive.
+  let reuseActivePrimary = false
+  if (!openTarget && !effectiveOpenInNewSim && parsedBridgeArgs.simIdSource === 'none') {
+    const probe = createBridgeFromParsed(parsedBridgeArgs)
+    try {
+      const sims = await probe.listSims()
+      const primary = sims.find((b) => b.isPrimary && b.readyState === 'open')
+      const firstOpen = sims.find((b) => b.readyState === 'open')
+      const active = primary ?? firstOpen
+      if (active) {
+        reuseActivePrimary = true
+        console.log(`  reusing active sim: ${active.id}`)
+      }
+    } catch {
+      // bridge not reachable — fall through to discovery
+    } finally {
+      probe.close()
+    }
+  }
+
+  if (
+    !openTarget &&
+    !reuseActivePrimary &&
+    (effectiveOpenInNewSim || parsedBridgeArgs.simIdSource === 'none')
+  ) {
+    const discovered = await discoverSootsimUrl()
+    if (!discovered) {
+      console.error('  error: no current sim and no sootsim target found')
+      await flushCliTelemetry()
+      process.exit(1)
+    }
+    openTarget = discovered
+  }
+
+  if (openTarget && targetDevice) {
+    // build against the shell that owns the bridge port this run will poll.
+    // resolve the shell from the already-selected bridge port so the flow
+    // cannot drive a sim in another live development stack.
+    const url = new URL(
+      await buildShellUrl(
+        openTarget,
+        resolveShellBaseUrlForBridgePort(parsedBridgeArgs.wsPort),
+      ),
+    )
+    url.searchParams.set('device', targetDevice)
+    openTarget = url.toString()
+  }
+
+  if (openTarget) {
+    const openArgs = [openTarget]
+    openArgs.push(...replaceArgs)
+    openArgs.push(...remapArgs)
+    if (effectiveOpenInNewSim) {
+      openArgs.push('--new')
+    }
+    openArgs.push('--no-describe')
+    if (parsedBridgeArgs.simIdSource === 'flag' && parsedBridgeArgs.simId) {
+      openArgs.push('--sim', parsedBridgeArgs.simId)
+    }
+    if (driverFlag) {
+      openArgs.push('--driver', driverFlag)
+      closeManagedDriverSimAfterRun = true
+    }
+    if (args.includes('--headless') && !headed) {
+      openArgs.push('--headless')
+    }
+    await runOpenCommand(openArgs, {
+      port: parsedBridgeArgs.wsPort,
+      timeoutMs: parsedBridgeArgs.commandTimeoutMs,
+    })
+    if (closeManagedDriverSimAfterRun) {
+      const openedSimId = readCurrentSimId()
+      if (openedSimId) ownedSimIds.add(openedSimId)
+    }
+  }
+
+  const resolvedBridgeArgs = parseBridgeCliArgs(args, bridgeArgOptions)
+  const pinnedSimId =
+    resolvedBridgeArgs.simIdSource === 'flag'
+      ? resolvedBridgeArgs.simId
+      : readCurrentSimId() || resolvedBridgeArgs.simId
+  // carry the source through so the target-sim notice reads `via --sim`
+  // (not the misleading `primary fallback — no sim pinned`) when the flow
+  // was actually pinned with --sim or a `sootsim use` selection.
+  const pinnedSimIdSource: typeof resolvedBridgeArgs.simIdSource =
+    resolvedBridgeArgs.simIdSource === 'flag' ? 'flag' : pinnedSimId ? 'saved' : 'none'
+  const bridge = createBridge(resolvedBridgeArgs.wsPort, {
+    commandTimeoutMs: resolvedBridgeArgs.commandTimeoutMs,
+    simId: pinnedSimId,
+    simIdSource: pinnedSimIdSource,
+  })
+  let driver: SootSimBridgeFlowRunner
+  const applyFlowFrontmatter = async () => {
+    const statusBarTime = frontmatter.env?.SOOTSIM_STATUS_BAR_TIME
+    if (statusBarTime) {
+      if (!/^(?:[1-9]|1[0-2]):[0-5][0-9]$/.test(statusBarTime)) {
+        throw new Error('SOOTSIM_STATUS_BAR_TIME must be a 12-hour time such as 9:41')
+      }
+      await bridge.send({
+        type: 'evaluate',
+        simId: driver.simId,
+        code: `window.dispatchEvent(new CustomEvent('sootsim:statusBarOverride', { detail: { time: ${JSON.stringify(statusBarTime)} } }))`,
+      })
+    }
+    if (targetTheme) {
+      await bridge.send({
+        type: 'call',
+        simId: driver.simId,
+        path: 'SootSim.bridges.settings.set',
+        args: ['colorScheme', targetTheme],
+      })
+    }
+    if (!targetDevice) return false
+    const currentUrl = await bridge.send({
+      type: 'evaluate',
+      simId: driver.simId,
+      code: 'window.location.href',
+    })
+    if (typeof currentUrl === 'string' && currentUrl.length > 0) {
+      const nextUrl = new URL(currentUrl)
+      nextUrl.searchParams.set('device', targetDevice)
+      driver.setSimRouteHint(nextUrl.toString())
+    }
+    return Boolean(
+      await bridge.send({
+        type: 'call',
+        simId: driver.simId,
+        path: 'SootSim.bridges.settings.set',
+        args: ['deviceModel', targetDevice],
+      }),
+    )
+  }
+  driver = new SootSimBridgeFlowRunner(bridge, {
+    screenshotDir,
+    flowDir: path.dirname(path.resolve(flowPath)),
+    screenshotPathMode,
+    screenshotLayers,
+    simId: pinnedSimId,
+    recordingOutputDir: record ? outDir : undefined,
+    recordingFormat: preview ? 'mp4' : 'webm',
+    // preview mode uploads to previewOrigin; entitlement check must
+    // talk to the same origin, not whatever the shared desktop sim
+    // happens to have cached.
+    billingOriginOverride: preview ? previewOrigin : undefined,
+    // any recording reached via a github installation token is a ci /
+    // pr-preview run, so allow it for preview uploads. local flow recording
+    // writes a file and matches `sootsim record --mode video`.
+    allowGitHubRecording: preview,
+    requireRecordingEntitlement: preview,
+    // re-arm the event recorder after every launchApp-with-reload. the
+    // recorder lives in-page state and gets wiped by window.location.reload.
+    onAfterLaunch: async () => {
+      const deviceChanged = await applyFlowFrontmatter()
+      if (deviceChanged) await driver.waitForTree(120000)
+      if (!preview) return
+      await bridge.send({
+        type: 'evaluate',
+        simId: driver.simId,
+        code: `(() => {
+          const r = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder
+          return r?.start?.() ?? false
+        })()`,
+      })
+    },
+  })
+  if (slow) driver.stepDelay = slow
+  // live step rail + pause gate in the sim devtools "test" tab, named by the
+  // flow file so the rail identifies what is running.
+  driver.liveStatus = new FlowLiveStatusReporter(
+    bridge,
+    path.basename(flowPath),
+    () => driver.simId,
+  )
+  // maestro default vars + flow-level `env:` frontmatter, defined into the
+  // flow's JS context before the first step (upstream withDefaultEnvVars +
+  // DefineVariablesCommand).
+  driver.js.putEnv('MAESTRO_FILENAME', path.basename(flowPath, path.extname(flowPath)))
+  if (frontmatter.env && typeof frontmatter.env === 'object') {
+    for (const [key, value] of Object.entries(frontmatter.env)) {
+      driver.js.putEnv(key, value)
+    }
+  }
+
+  let profileResult: SootSimFlowProfileResult | null = null
+  let videoPath: string | null = null
+  let videoDurationMs: number | null = null
+  let capturedEvents: Array<Record<string, any>> | null = null
+  let previewScreenshotPath: string | null = null
+  let failureBundleDir: string | null = null
+  let exitCode = 0
+  const startsWithLaunchApp = !!steps[0]?.launchApp
+  try {
+    if (!startsWithLaunchApp) {
+      await driver.waitForTree(120000)
+    }
+    const deviceChanged = await applyFlowFrontmatter()
+    if (deviceChanged && !startsWithLaunchApp) await driver.waitForTree(120000)
+    // preview replay must reproduce the SAME initial conditions the agent
+    // explored from. the explore session runs on a fresh ephemeral profile
+    // (cold, logged-out), so its recorded steps assume that cold start —
+    // e.g. step 1 taps a dev/login button. but the replay tab reuses the
+    // explore tab's now-dirtied storage (persisted auth/session), so without
+    // a reset the app boots already-authenticated and the recorded login
+    // step targets an element that no longer exists — the flow hangs on
+    // step 1 ("made no progress … bridge or bundle probably hung"). flows
+    // that open with an explicit launchApp manage their own state; every
+    // other preview flow gets a clean cold launch here so the recording
+    // captures the same journey from the same starting point. app-agnostic,
+    // no per-repo configuration — the bot just figures it out.
+    // skip when the caller already established a clean cold state (e.g. the
+    // contrastbot run.sh pre-replay reset reopens an --ephemeral sim: fresh
+    // profile, logged-out, brought to readiness). a second clearState+reload
+    // here is redundant and triggers a sim-id rotation on the reload that
+    // routes the flow to a stale sim, hanging step 1 ("made no progress …
+    // bridge or bundle probably hung"). one reset is enough — the bot
+    // signals it did one via SOOTSIM_PREVIEW_RESET_DONE.
+    if (preview && !startsWithLaunchApp && !process.env.SOOTSIM_PREVIEW_RESET_DONE) {
+      await driver.launchApp({ clearState: true })
+    }
+    if (record) {
+      if (startsWithLaunchApp) {
+        driver.prepareRecording()
+      } else {
+        await driver.startRecording()
+      }
+    }
+    if (profile) {
+      await driver.startProfile()
+    }
+    if (preview) {
+      // start the preview event recorder on the tab so agent-driven taps
+      // (via sootsim:agentAction) land in the capture stream for replay.
+      // some shells expose the recorder via window.SootSim, others via
+      // the legacy alias only — try both.
+      const started = await bridge.send({
+        type: 'evaluate',
+        simId: driver.simId,
+        code: `(() => {
+          const r = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder
+          return r?.start?.() ?? false
+        })()`,
+      })
+      if (!started) {
+        console.warn(
+          '  warn: eventRecorder.start() returned false — preview will upload bundle without replay events',
+        )
+      }
+    }
+    await driver.runFlow(steps)
+    if (profile) {
+      profileResult = await driver.stopProfile()
+    }
+    await driver.waitForRecordingTail({ maxMs: tailWaitMs, smart: preview })
+    if (record) {
+      videoPath = await driver.stopRecording()
+      videoDurationMs = driver.getLastRecordingDurationMs()
+    }
+    if (preview) {
+      capturedEvents = (await bridge.send({
+        type: 'evaluate',
+        simId: driver.simId,
+        code: `(() => {
+          const r = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder
+          return r?.stop?.() ?? []
+        })()`,
+      })) as Array<Record<string, any>>
+      console.log(`  captured ${capturedEvents.length} replay events`)
+      previewScreenshotPath = path.join(screenshotDir, 'preview-final.png')
+      await driver.captureScreenshot(previewScreenshotPath)
+      console.log(`  final screenshot: ${previewScreenshotPath}`)
+    }
+
+    const screenshotSteps = steps.filter(
+      (s: any) => s && typeof s === 'object' && 'takeScreenshot' in s,
+    ).length
+    console.log(`\n  + completed (${steps.length} steps)`)
+    if (screenshotSteps > 0) {
+      // surface where the assets actually landed so the user doesn't have to
+      // grep through verbose [flow] step output for paths
+      console.log(`  screenshots: ${screenshotSteps} → ${screenshotDir}`)
+    }
+    if (profileResult) {
+      printFlowProfile(profileResult)
+    }
+    if (videoPath) {
+      console.log(`  video: ${videoPath}`)
+    }
+    console.log()
+  } catch (err: any) {
+    if (profile && !profileResult) {
+      try {
+        profileResult = await driver.stopProfile()
+      } catch {
+        // ignore profiling teardown failures while already handling the main error
+      }
+    }
+    if (record && !videoPath) {
+      try {
+        videoPath = await driver.stopRecording()
+        videoDurationMs = driver.getLastRecordingDurationMs()
+      } catch (recordErr: any) {
+        console.warn(
+          `  recording stop failed: ${recordErr?.message || String(recordErr)}`,
+        )
+      }
+    }
+    if (preview && !capturedEvents) {
+      try {
+        capturedEvents = (await bridge.send({
+          type: 'evaluate',
+          simId: driver.simId,
+          code: `(() => {
+            const r = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder
+            return r?.stop?.() ?? []
+          })()`,
+        })) as Array<Record<string, any>>
+        console.log(`  captured ${capturedEvents.length} partial replay events`)
+      } catch (eventErr: any) {
+        console.warn(
+          `  event recorder stop failed: ${eventErr?.message || String(eventErr)}`,
+        )
+      }
+    }
+    console.error(`\n  x failed: ${err.message}\n`)
+    if (profileResult) {
+      console.log('  partial profile:')
+      printFlowProfile(profileResult)
+    }
+    if (videoPath) {
+      console.log(`  partial video: ${videoPath}`)
+    }
+    try {
+      // rich per-failure bundle: screenshot + describe.json + a11y +
+      // tree + console + failed-requests. dir is named by the failing
+      // step so consecutive failing runs don't overwrite each other.
+      const failedStep = driver.lastFailedStep
+      const bundleName = failedStep
+        ? `step-${String(failedStep.index + 1).padStart(2, '0')}-${failedStep.kind}`
+        : 'unstaged'
+      const bundleDir = path.join(screenshotDir, bundleName)
+      await driver.captureFailureBundle(bundleDir, {
+        error: err,
+        stepIndex: failedStep?.index,
+        stepKind: failedStep?.kind,
+        stepTarget: failedStep?.target,
+      })
+      failureBundleDir = bundleDir
+      console.log(`  failure bundle: ${bundleDir}`)
+      console.log(
+        `    (contents: screenshot.png, describe.json, a11y.txt, tree.txt, console.json, error.json)`,
+      )
+    } catch (bundleErr) {
+      // fall back to the bare screenshot if the full bundle blew up —
+      // at least the viewer has one thing to look at.
+      try {
+        const errShot = path.join(screenshotDir, 'error.png')
+        await driver.captureScreenshot(errShot)
+        console.log(`  error screenshot: ${errShot}`)
+      } catch {}
+      console.log(
+        `  (failure bundle capture failed: ${
+          bundleErr instanceof Error ? bundleErr.message : String(bundleErr)
+        })`,
+      )
+    }
+    await printBridgeFailureDiagnostics(bridge, {
+      errorsCommand: `sootsim get errors 5${driver.simId ? ` --sim ${driver.simId}` : ''}`,
+      warningsCommand: `sootsim get warnings 5${driver.simId ? ` --sim ${driver.simId}` : ''}`,
+      requestsCommand: `sootsim get requests 5${driver.simId ? ` --sim ${driver.simId}` : ''}`,
+    })
+    exitCode = 1
+  }
+
+  await driver.liveStatus?.end(exitCode === 0 ? 'passed' : 'failed')
+
+  // under --preview, kick the captured events into the preview uploader so the viewer
+  // gets a real /preview/<id> with scrubbable replay. failed flows upload the
+  // partial recording when available so dashboard runs can link to the trace.
+  if (preview && (exitCode === 0 || videoPath || capturedEvents)) {
+    try {
+      const eventsJsonlGz = await prepareEventsFile(capturedEvents ?? [])
+      const uploadArgs = ['--origin', previewOrigin, '--events', eventsJsonlGz]
+      if (previewPublicOrigin) {
+        uploadArgs.push('--public-origin', previewPublicOrigin)
+      }
+      // chain the recorded mp4 so preview-page can layer it over the
+      // canvas during scrub for smooth motion while the real app
+      // catches up.
+      if (videoPath) uploadArgs.push('--video', videoPath)
+      if (previewScreenshotPath) {
+        uploadArgs.push('--screenshot', previewScreenshotPath)
+      }
+      if (videoPath && videoDurationMs && Number.isFinite(videoDurationMs)) {
+        uploadArgs.push('--video-duration-ms', String(Math.round(videoDurationMs)))
+        uploadArgs.push('--recorded-duration-ms', String(Math.round(videoDurationMs)))
+      }
+      const recordingStartedAtMs = driver.getLastRecordingStartedAtMs()
+      if (recordingStartedAtMs && Number.isFinite(recordingStartedAtMs)) {
+        uploadArgs.push(
+          '--recording-started-at-ms',
+          String(Math.round(recordingStartedAtMs)),
+        )
+      }
+      if (parsedBridgeArgs.wsPort) {
+        uploadArgs.push('--port', String(parsedBridgeArgs.wsPort))
+      }
+      if (driver.simId) {
+        uploadArgs.push('--sim', driver.simId)
+      }
+      if (previewOpen) uploadArgs.push('--open')
+      if (previewOwner) uploadArgs.push('--owner', previewOwner)
+      if (previewRepo) uploadArgs.push('--repo', previewRepo)
+      uploadArgs.push('--run-scope', previewRunScope)
+      if (previewBillingKind) {
+        uploadArgs.push('--billing-kind', previewBillingKind)
+      }
+      console.log(`\n  preparing preview upload…`)
+      const flowTraceSteps = driver.getFlowTraceSteps()
+      if (flowTraceSteps.length > 0) {
+        uploadArgs.push(
+          '--timeline-events',
+          await prepareFlowStepTimelineFile(flowTraceSteps),
+        )
+      }
+      const snapshotManifest = await prepareFlowSnapshotManifest(
+        flowTraceSteps,
+        recordingStartedAtMs,
+      )
+      if (snapshotManifest) {
+        uploadArgs.push('--snapshot-manifest', snapshotManifest)
+      }
+      if (failureBundleDir) {
+        // failed runs ship the per-step debug bundle with the share so the
+        // dashboard's run row can show the failing screen + full context.
+        uploadArgs.push('--failure-bundle', failureBundleDir)
+      }
+      const frameStats = driver.getLastRecordingFrameStats()
+      if (frameStats) {
+        uploadArgs.push('--trace-frame-stats', await prepareFrameStatsFile(frameStats))
+      }
+      const { runUpload } = await import('./upload')
+      lastPreviewUploadResult = await runUpload(uploadArgs, {})
+    } catch (err: any) {
+      console.error(`  preview upload failed: ${err?.message || err}`)
+      exitCode = 1
+    }
+  }
+
+  lastFlowTraceSteps = driver.getFlowTraceSteps()
+
+  bridge.close()
+
+  if (closeManagedDriverSimAfterRun) {
+    if (driver.simId) ownedSimIds.add(driver.simId)
+    await closeFlowOwnedSims(parsedBridgeArgs.wsPort, parsedBridgeArgs.commandTimeoutMs, [
+      ...ownedSimIds,
+    ])
+  } else if (driver.simId && driver.simId !== pinnedSimId) {
+    // `launchApp clearState` rotates the sim id mid-flow (the shell reconnects
+    // under a fresh id). the runner tracks that in-memory, but a directory run
+    // (`sootsim maestro test <dir>`) spawns the next flow fresh — it re-reads
+    // the saved sim id, which would still point at the pre-rotation sim and
+    // fail with "sim not responding / stale orphan". persist the rotated id so
+    // the next flow reuses the live sim. only when we're NOT closing it.
+    saveCurrentSimId(driver.simId)
+  }
+
+  // flush before returning to caller — caller typically calls
+  // process.exit(returnedCode), and node's `exit` hook can't await, so
+  // without this the flow telemetry (and any chained upload's events)
+  // get silently dropped.
+  await flushCliTelemetry()
+  return exitCode
+}
+
+async function closeFlowOwnedSims(
+  wsPort: number,
+  commandTimeoutMs: number,
+  simIds: string[],
+): Promise<void> {
+  const ids = [...new Set(simIds.filter(Boolean))]
+  if (ids.length === 0) return
+  const bridge = createBridge(wsPort, { commandTimeoutMs })
+  try {
+    const sims = await bridge.listSims()
+    const openIds = ids.filter((id) =>
+      sims.some((sim) => sim.id === id && sim.readyState === 'open'),
+    )
+    if (openIds.length === 0) return
+    const result = await closeSimsBulk(bridge, wsPort, commandTimeoutMs, openIds)
+    await terminatePlaywrightHostsForSims(sims, openIds)
+    if (result.closed.length > 0) {
+      console.log(`  closed flow sim(s): ${result.closed.join(', ')}`)
+    }
+    if (result.remaining.length > 0) {
+      console.warn(
+        `  warn: flow sim(s) still connected after close: ${result.remaining.join(', ')}`,
+      )
+    }
+  } catch (err) {
+    console.warn(
+      `  warn: failed to close flow sim(s): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    )
+  } finally {
+    bridge.close()
+  }
+}
+
+// write the captured event stream to a gzipped jsonl file in a temp dir.
+// returns the absolute path for the upload command to pick up.
+async function prepareEventsFile(events: Array<Record<string, any>>): Promise<string> {
+  const { gzipSync } = await import('zlib')
+  const lines =
+    events.map((e) => JSON.stringify(e)).join('\n') + (events.length ? '\n' : '')
+  const gz = gzipSync(Buffer.from(lines, 'utf8'))
+  const outPath = path.join(tmpdir(), `sootsim-events-${Date.now()}.jsonl.gz`)
+  fs.writeFileSync(outPath, gz)
+  console.log(`  events: ${events.length} written to ${outPath} (${gz.length} bytes gz)`)
+  return outPath
+}
+
+async function prepareFlowStepTimelineFile(
+  steps: SootSimFlowTraceStep[],
+): Promise<string> {
+  const { gzipSync } = await import('zlib')
+  const events = steps.map((step, index) => ({
+    schemaVersion: 1,
+    t: step.endedAtMs,
+    seq: 1_000_000 + index,
+    context: 'host',
+    kind: 'flow-step',
+    id: `flow-step-${step.stepIndex}`,
+    data: {
+      stepIndex: step.stepIndex,
+      stepNumber: step.stepIndex + 1,
+      stepName: step.stepName,
+      ...(step.targetLabel ? { targetLabel: step.targetLabel } : {}),
+      status: step.status,
+      durationMs: step.durationMs,
+      startedAtMs: step.startedAtMs,
+      endedAtMs: step.endedAtMs,
+      ...(step.error ? { error: step.error } : {}),
+    },
+  }))
+  const lines = events.map((event) => JSON.stringify(event)).join('\n') + '\n'
+  const gz = gzipSync(Buffer.from(lines, 'utf8'))
+  const outPath = path.join(tmpdir(), `sootsim-flow-steps-${Date.now()}.jsonl.gz`)
+  fs.writeFileSync(outPath, gz)
+  console.log(
+    `  flow trace: ${events.length} step events written to ${outPath} (${gz.length} bytes gz)`,
+  )
+  return outPath
+}
+
+async function prepareFlowSnapshotManifest(
+  steps: SootSimFlowTraceStep[],
+  recordingStartedAtMs: number | null,
+): Promise<string | null> {
+  if (!recordingStartedAtMs) return null
+  const snapshots = steps.flatMap((step) =>
+    step.screenshotPath
+      ? [
+          {
+            id: `flow-step-${step.stepIndex}`,
+            label: step.targetLabel ?? `Step ${step.stepIndex + 1}`,
+            kind: 'interaction',
+            t: Math.max(0, step.endedAtMs - recordingStartedAtMs),
+            path: step.screenshotPath,
+          },
+        ]
+      : [],
+  )
+  if (snapshots.length === 0) return null
+  const outPath = path.join(tmpdir(), `sootsim-flow-snapshots-${Date.now()}.json`)
+  fs.writeFileSync(outPath, JSON.stringify(snapshots))
+  console.log(`  flow snapshots: ${snapshots.length} written to ${outPath}`)
+  return outPath
+}
+
+async function prepareFrameStatsFile(frameStats: unknown): Promise<string> {
+  const outPath = path.join(tmpdir(), `sootsim-frame-stats-${Date.now()}.json`)
+  fs.writeFileSync(outPath, JSON.stringify(frameStats))
+  console.log(`  frame stats: written to ${outPath}`)
+  return outPath
+}
+
+async function runFlowSession(args: string[]) {
+  const subcommand = args[0]
+  const getFlag = (name: string) => args.find((_, i) => args[i - 1] === name)
+
+  switch (subcommand) {
+    case 'start': {
+      const { path, state } = startFlowSession()
+      console.log(`  flow draft started`)
+      console.log(`  session: ${path}`)
+      console.log(`  steps: ${state.steps.length}`)
+      return
+    }
+
+    case 'keep':
+    case 'good': {
+      const result = keepFlowCandidate()
+      if (!result.active) {
+        console.error('  no active flow draft — run `sootsim maestro start` first')
+        process.exit(1)
+      }
+      if (!result.kept) {
+        console.log('  no pending action to keep')
+        return
+      }
+      console.log(`  kept: ${result.candidate.summary}`)
+      console.log(`  steps: ${result.stepCount}`)
+      return
+    }
+
+    case 'end': {
+      const outputPath =
+        getFlag('--output') || (args[1] && !args[1].startsWith('-') ? args[1] : undefined)
+      const validate = args.includes('--validate') || args.includes('--video')
+      const video = args.includes('--video')
+      // ending the draft commits the trailing pending action. the last
+      // successful `do` is presumably one the user wants; without this,
+      // `maestro start → do → maestro end` (no explicit keep) exported an empty
+      // [] and silently dropped the work (F13-4).
+      const autoKept = keepFlowCandidate()
+      if (autoKept.active && autoKept.kept) {
+        console.log(`  auto-kept trailing action: ${autoKept.candidate.summary}`)
+      }
+      const result = exportFlowSession(
+        outputPath || (validate ? createDraftValidationPath() : undefined),
+      )
+      if (!result.active) {
+        console.error('  no active flow draft — run `sootsim maestro start` first')
+        process.exit(1)
+      }
+      if (!result.valid) {
+        console.error('  flow draft is not valid:')
+        for (const issue of result.issues) console.error(`    - ${issue}`)
+        console.error(
+          '  draft preserved — keep at least one real interaction or run `sootsim maestro start` to reset',
+        )
+        process.exit(1)
+      }
+
+      if (validate) {
+        const playbackArgs = buildFlowValidationArgs(args, result.outputPath)
+        const exitCode = await runFlowPlayback(playbackArgs)
+        if (exitCode !== 0) {
+          console.error(
+            '\n  validation failed — draft preserved so you can keep iterating',
+          )
+          process.exitCode = exitCode
+          return
+        }
+
+        finalizeFlowSession()
+        console.log(
+          `  flow draft validated (${result.stepCount} step${result.stepCount === 1 ? '' : 's'})`,
+        )
+        if (result.outputPath) {
+          console.log(`  saved: ${result.outputPath}`)
+        }
+        if (video) {
+          console.log('  video: recorded during validation run')
+        }
+        return
+      }
+
+      finalizeFlowSession()
+      console.log(
+        `  flow draft ended (${result.stepCount} step${result.stepCount === 1 ? '' : 's'})`,
+      )
+      if (result.outputPath) {
+        console.log(`  saved: ${result.outputPath}`)
+        console.log(`  next: sootsim maestro test ${result.outputPath} --record`)
+        return
+      }
+      console.log('')
+      process.stdout.write(result.yaml)
+      return
+    }
+
+    case 'validate': {
+      const flowPath = args[1]
+      if (!flowPath || flowPath.startsWith('-')) {
+        console.error('  usage: sootsim maestro validate <path>')
+        process.exit(1)
+      }
+      const issues = validateFlowFile(flowPath)
+      if (issues.length > 0) {
+        console.error(`  x ${flowPath} failed validation:`)
+        for (const issue of issues) console.error(`    - ${issue}`)
+        process.exit(1)
+      }
+      console.log(`  + ${flowPath} looks valid`)
+      return
+    }
+  }
+}
+
+// the subcommand / flow-file path is the first positional arg, but a
+// `--sim <id>` pair can sit in front of it: bin.ts prepends the global
+// `--sim` to every command's args, and `sootsim maestro --sim a2 start` is a
+// documented form. hoist a leading `--sim <value>` to the end so `args[0]`
+// is the real subcommand again (downstream getFlag / parseBridgeCliArgs
+// still find `--sim` wherever it lands). without this, `--sim 6a5 flow
+// start` parsed `--sim` as the flow path and failed `--sim not found`.
+export function hoistLeadingSimFlag(args: string[]): string[] {
+  if (args[0] === '--sim' && args.length >= 2) {
+    return [...args.slice(2), '--sim', args[1]]
+  }
+  return args
+}
+
+export async function runMaestroAuthoring(rawArgs: string[]): Promise<number> {
+  const args = hoistLeadingSimFlag(rawArgs)
+  const subcommand = args[0]
+  if (
+    subcommand === 'start' ||
+    subcommand === 'keep' ||
+    subcommand === 'good' ||
+    subcommand === 'end' ||
+    subcommand === 'validate'
+  ) {
+    await runFlowSession(args)
+    return 0
+  }
+
+  const exitCode = await runFlowPlayback(args)
+  if (exitCode !== 0) {
+    process.exitCode = exitCode
+  }
+  return exitCode
+}
+
+function printFlowProfile(result: SootSimFlowProfileResult) {
+  console.log('')
+  printShellPerfReport(result)
+}
+function createDraftValidationPath() {
+  return path.join(tmpdir(), `sootsim-flow-draft-${Date.now()}.yaml`)
+}
+
+function buildFlowValidationArgs(args: string[], outputPath: string | null) {
+  if (!outputPath) {
+    throw new Error('validated flow draft requires an output path')
+  }
+
+  const nextArgs = [outputPath]
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--validate' || arg === '--video') continue
+    if (arg === '--output') {
+      i += 1
+      continue
+    }
+    if (i === 1 && !arg.startsWith('-')) {
+      continue
+    }
+    nextArgs.push(arg)
+  }
+
+  if (!nextArgs.includes('--record') && args.includes('--video')) {
+    nextArgs.push('--record')
+  }
+  return nextArgs
+}