rnxsim 0.1.313 → 0.1.314

package/cli/commands/record.ts

@@ -0,0 +1,1434 @@
+// sootsim record — drives the engine's built-in canvas recorder over
+// the WS bridge. no playwright, no ffmpeg. encoding happens in the
+// running sootsim page (webm via MediaRecorder, mp4 via WebCodecs, gif
+// via gifenc, raw png frames via a shared bitmap sampler).
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'fs'
+import { homedir, tmpdir } from 'os'
+import { dirname, extname, join, resolve } from 'path'
+import { githubUploadIdentity, resolveCliAuth } from '../auth'
+import { getCliIdentityKey } from '../current-sim'
+import { openUrl } from '../open-url'
+import { ensureCliRecordingEntitlement } from '../recording-access'
+import { resolveRunProvenance } from '../run-registry'
+import {
+  checkSimHealth,
+  createBridgeFromParsed,
+  parseBridgeCliArgs,
+  type WsBridge,
+} from '../ws-bridge'
+
+interface RecordOptions {
+  port?: number
+  verbose?: boolean
+}
+
+type OutputFormat = 'webm' | 'mp4' | 'gif' | 'png'
+
+// recording mode — 'video' is a local webm/mp4 download via the headless
+// recorder bridge (current CLI default). 'live' and 'combined' route
+// through the recording store so they capture pointer events (and, for
+// combined, video) and upload to /preview/<id>. mirrors RecordingMode in
+// packages/sootsim-engine/src/recording/recordingStore.ts.
+type RecordMode = 'video' | 'live' | 'combined'
+
+// how long to wait for the live/combined upload to settle after stop. dev
+// bundles routinely include tens of MB of transformed JS plus captured
+// request bodies; 60s was too tight and left valid PR-preview recordings
+// uploading in the page after the CLI had already reported failure.
+const UPLOAD_TIMEOUT_MS = 240_000
+
+// how long `record start --mode live/combined` waits for each setup bridge
+// eval (auth inject, store start) to round-trip. unlike the light `video`
+// start (a single __sootsimRecorder.start), the store-backed start must reach
+// an engine that — on a contended CI runner, right after the PR-preview agent
+// drove a populated app — is saturated rendering at a few fps and cannot answer
+// a bridge eval within the 15s the video path uses. that 15s cap made
+// `record start` time out, the agent retry it many times, and the leading idle
+// from the failed attempts blow the 15s first-interaction quality gate
+// (preview-quality.ts) so the take was rejected even once it finally recorded.
+// give the upload-bearing start the slack the atomic combined path
+// (runRecord, commandTimeoutMs 60s) already uses, plus headroom for a starved
+// engine. video start stays light at 15s.
+const STORE_RECORD_START_TIMEOUT_MS = 90_000
+
+// per-step bridge-eval budget for local-file capture (gif / video). the
+// blanket 60s command timeout means a contended or wedged render host
+// produces a 60s generic "command timed out" hang with no hint which step
+// stalled (QA F19-5). scope each capture eval to its own recording duration
+// plus a generous encode/teardown allowance so a stalled host fails fast
+// and actionably. the bitmap-capture lock now self-releases on abandon
+// (bitmap-capture.ts), so recovery is simply to retry.
+const CAPTURE_STEP_ENCODE_BUDGET_MS = 30_000
+
+async function evalCaptureStep<T>(
+  bridge: WsBridge,
+  code: string,
+  step: string,
+  durationMs: number,
+): Promise<T> {
+  const timeoutMs = Math.max(20_000, durationMs + CAPTURE_STEP_ENCODE_BUDGET_MS)
+  try {
+    return (await bridge.send({ type: 'evaluate', code }, { timeoutMs })) as T
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    if (/^command timed out after \d+s$/.test(msg)) {
+      console.error(
+        `  ${step} stalled — the render host did not finish within ` +
+          `${Math.round(timeoutMs / 1000)}s; it is likely contended or wedged.\n` +
+          `  the capture lock auto-releases, so simply retry the recording.\n` +
+          `  if it persists, recover the sim with \`rnxsim close --sim <id>\`.`,
+      )
+      process.exit(1)
+    }
+    // a leaked/contended render-host streaming session surfaces as an
+    // engine-side error delivered over the WS bridge. on the gif/video
+    // start path this rejection previously had no upstream catch, so it
+    // escaped as a raw unhandled stack trace AND the process self-exited
+    // 0 (false success, no file written) — QA F20-1. handle it here:
+    // actionable message, non-zero exit, no stack.
+    if (
+      /render host not available|already streaming|already recording|lock already held/i.test(
+        msg,
+      )
+    ) {
+      console.error(
+        `  ${step} failed: ${msg}\n` +
+          `  a prior recording was abandoned and its capture is still\n` +
+          `  releasing. the lock self-heals in ~${Math.round(
+            (durationMs + 20_000) / 1000,
+          )}s — retry then, or recover now with\n` +
+          `  \`rnxsim close --sim <id>\` and reopen the sim.`,
+      )
+      process.exit(1)
+    }
+    // never let any other capture-eval rejection escape as an unhandled
+    // promise (raw stack + false exit 0). surface it and exit non-zero.
+    console.error(`  ${step} failed: ${msg}`)
+    process.exit(1)
+  }
+}
+
+// value-taking flags that may legitimately appear before the subcommand —
+// notably `--sim`, which bin.ts prepends to the command args. their values
+// must not be mistaken for the subcommand.
+const RECORD_VALUE_FLAGS = new Set([
+  '--sim',
+  '--port',
+  '-p',
+  '--mode',
+  '--duration',
+  '--fps',
+  '--format',
+  '--output',
+  '-o',
+  '--frames',
+  '--max-width',
+  '--origin',
+  '--owner',
+  '--repo',
+])
+const RECORD_SUBCOMMANDS = new Set([
+  'start',
+  'stop',
+  'cancel',
+  'status',
+  'prelude-start',
+  'upload',
+])
+
+// the record subcommand (start/stop/cancel/status) is the first non-flag
+// positional — NOT necessarily args[0]. bin.ts prepends `--sim <id>` when a
+// global --sim target is set, so a naive args[0] check silently fell through
+// to the atomic-record path and started a spurious recording (F41).
+function findRecordSubcommand(args: string[]): { name: string; index: number } | null {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a.startsWith('-')) {
+      if (RECORD_VALUE_FLAGS.has(a)) i++ // skip the flag's value
+      continue
+    }
+    return RECORD_SUBCOMMANDS.has(a) ? { name: a, index: i } : null
+  }
+  return null
+}
+
+type RepoScope = { owner: string; repo: string } | null
+
+// git provenance for PR-preview shares, read from the github-actions env
+// (run.sh exports these). repo-agnostic: every PR-preview run carries the
+// standard GITHUB_* vars, with CONTRAST_* overrides matching resolveCliAuth.
+// merged into the upload identity so the org/recent feed shows the same
+// branch / PR title + "sha · author" for previews as for branch-builds.
+function readRepoScope(args: string[]): RepoScope {
+  const owner = valueOf(args, '--owner')?.trim()
+  const repo = valueOf(args, '--repo')?.trim()
+  if ((owner && !repo) || (!owner && repo)) {
+    console.error('  --owner and --repo must be provided together')
+    process.exit(1)
+  }
+  return owner && repo ? { owner, repo } : null
+}
+
+export async function runRecord(args: string[], opts: RecordOptions) {
+  // note: `--help` / `-h` never reach here — bin.ts intercepts them and
+  // renders the registry-driven help page (packages/sootsim-skills meta.ts).
+
+  const sub = findRecordSubcommand(args)
+  if (sub) {
+    // drop the subcommand token; the rest (incl. any --sim/--port) flows on
+    // to the subcommand handlers, which parse bridge flags themselves.
+    const rest = [...args.slice(0, sub.index), ...args.slice(sub.index + 1)]
+    if (sub.name === 'start') {
+      await recordStart(rest, opts)
+      return
+    }
+    if (sub.name === 'prelude-start') {
+      await recordPreludeStart(rest, opts)
+      return
+    }
+    if (sub.name === 'upload') {
+      const { runUpload } = await import('./upload')
+      await runUpload(rest, opts)
+      return
+    }
+    if (sub.name === 'stop') {
+      await recordStop(rest, opts)
+      return
+    }
+    if (sub.name === 'cancel') {
+      await recordCancel(rest, opts)
+      return
+    }
+    await recordStatus(rest, opts)
+    return
+  }
+
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    stripBooleanFlags: ['--no-shell', '--shell-only', '--open', '--lockstep'],
+    stripValueFlags: [
+      '--mode',
+      '--duration',
+      '--fps',
+      '--format',
+      '--output',
+      '--frames',
+      '--max-width',
+      '--origin',
+      '--owner',
+      '--repo',
+    ],
+  })
+  const mode = parseMode(valueOf(args, '--mode'))
+  const layers: 'tenant' | 'shell' | undefined = args.includes('--shell-only')
+    ? 'shell'
+    : args.includes('--no-shell')
+      ? 'tenant'
+      : undefined
+  const formatArg = valueOf(args, '--format') as OutputFormat | undefined
+  if (formatArg && !['webm', 'mp4', 'gif', 'png'].includes(formatArg)) {
+    console.error(`  invalid --format "${formatArg}" — expected webm | mp4 | gif | png`)
+    process.exit(1)
+  }
+  const outputArg = valueOf(args, '--output')
+  const durationSec = Number(valueOf(args, '--duration') ?? '10')
+  if (!Number.isFinite(durationSec) || durationSec <= 0) {
+    console.error(
+      `  invalid --duration "${valueOf(args, '--duration')}" — expected a positive number of seconds`,
+    )
+    process.exit(1)
+  }
+  // upper bound: a fat-fingered `--duration 99999` (≈27.7h) otherwise
+  // started a runaway recording with no warning (QA F23-3). 600s mirrors
+  // the server's MAX_FLOW_VIDEO_DURATION_MS — live/combined uploads past
+  // it are rejected anyway, and no legitimate atomic capture runs longer
+  // (the bitmap watchdog tears down well before that). float seconds stay
+  // allowed (rounded to ms below) — unlike --frames, a duration is a time,
+  // not a count, so sub-second precision is meaningful.
+  const MAX_DURATION_SEC = 600
+  if (durationSec > MAX_DURATION_SEC) {
+    console.error(
+      `  invalid --duration "${valueOf(args, '--duration')}" — exceeds the ${MAX_DURATION_SEC}s (10m) maximum`,
+    )
+    process.exit(1)
+  }
+  const fps = Number(valueOf(args, '--fps') ?? '30')
+  const framesArg = valueOf(args, '--frames')
+  // --frames is a count, not a duration — reject 0 / negatives / fractions
+  // up front instead of silently "saving 0 frames" (F11-3), mirroring the
+  // --duration guard above.
+  if (framesArg !== undefined) {
+    const n = Number(framesArg)
+    if (!Number.isInteger(n) || n <= 0) {
+      console.error(
+        `  invalid --frames "${framesArg}" — expected a positive integer count`,
+      )
+      process.exit(1)
+    }
+  }
+  const openAfter = args.includes('--open')
+  const maxWidth = valueOf(args, '--max-width')
+    ? Number(valueOf(args, '--max-width'))
+    : undefined
+  if (args.includes('--lockstep')) {
+    // atomic mode times the recording in wall seconds, but lockstep virtual
+    // time runs slower than the wall clock, so `--duration` would lie about
+    // the captured span. drive lockstep through start/stop instead.
+    console.error(
+      '  --lockstep works with `record start` / `record stop` (stateful mode) — atomic --duration is wall-clock and cannot bound a virtual-time capture',
+    )
+    process.exit(1)
+  }
+
+  const durationMs = Math.max(100, Math.round(durationSec * 1000))
+  // --origin explicitly pins the billing/upload origin. it wins over the
+  // saved desktop-session origin so a key minted against a local :3000
+  // stack verifies there instead of prod (the e2e blocker — F12).
+  const originOverride = valueOf(args, '--origin')
+  const repoScope = readRepoScope(args)
+
+  // live / combined route through the recording store (events + optional
+  // video, upload to /preview/<id>) instead of the headless recorder.
+  if (mode === 'live' || mode === 'combined') {
+    // --output only applies to local-file capture (video/gif/png). live and
+    // combined upload to /preview/<id> and write no local file — say so
+    // rather than silently swallowing the flag.
+    if (outputArg) {
+      console.log(
+        `  note: --output is ignored for --mode ${mode} — the recording uploads to /preview/<id>`,
+      )
+    }
+    // --no-shell / --shell-only select which layers the captured video
+    // shows. live mode records events only (no video), so the flag has
+    // nothing to act on there — say so rather than dropping it silently
+    // (F12-1).
+    if (layers && mode === 'live') {
+      console.log(
+        `  note: --${layers === 'shell' ? 'shell-only' : 'no-shell'} is ignored for --mode live — live recordings capture events only, no video`,
+      )
+    }
+    // only the upload-bearing modes touch the cloud, so gate the recording
+    // entitlement here, not on local-file video/gif/png capture (F19).
+    // allowGitHubAuth mirrors preview flow recording: the github pr-preview
+    // runner authenticates with an installation token, not RNX_API_KEY
+    // (zero-secrets design). the bypass only fires when auth.kind ===
+    // 'github' (ci/preview); local paid users have session/
+    // api-key auth and still go through the billing entitlement check.
+    await ensureCliRecordingEntitlement('record', {
+      originOverride,
+      allowGitHubAuth: true,
+    })
+    const bridge = createBridgeFromParsed({ ...parsed, commandTimeoutMs: 60_000 })
+    try {
+      await assertStoreBridgesAvailable(bridge)
+      await assertGuestBundleLoaded(bridge, mode)
+      if (mode === 'combined') await assertTabVisibleForCapture(bridge)
+      await injectPreviewSessionAuth(bridge, originOverride, repoScope)
+      const started = await evalStoreStart(
+        bridge,
+        mode,
+        mode === 'combined' ? layers : undefined,
+      )
+      if (!started.ok) {
+        console.error(
+          `  start failed: recording store refused to start (${mode})` +
+            (started.error ? `: ${started.error}` : ''),
+        )
+        process.exit(1)
+      }
+      console.log(`  recording ${mode} for ${durationSec}s`)
+      await new Promise((r) => setTimeout(r, durationMs))
+      await evalStoreStop(bridge)
+      const result = await pollStoreUpload(bridge)
+      handleStoreUploadResult(result, openAfter, mode)
+    } finally {
+      bridge.close()
+    }
+    return
+  }
+
+  const framesCount = framesArg ? Number(framesArg) : null
+  const format: OutputFormat = resolveFormat(formatArg, outputArg, framesCount)
+
+  // --open launches the uploaded /preview/<id> page — local-file capture
+  // (video/gif/png) produces no URL, so say it's ignored rather than
+  // swallowing the flag silently (F12-4).
+  if (openAfter) {
+    console.log(
+      `  note: --open is ignored for local-file capture — it applies to --mode live/combined`,
+    )
+  }
+
+  const bridge = createBridgeFromParsed({ ...parsed, commandTimeoutMs: 60_000 })
+  try {
+    await assertRecorderAvailable(bridge)
+    await assertTabVisibleForCapture(bridge)
+
+    if (format === 'png') {
+      const count = framesCount ?? 10
+      const outDir = resolveRecordingOutput(outputArg, `sootsim-frames-${stamp()}`)
+      // --frames writes one png PER frame, so --output names a directory, not
+      // a file. a caller passing `--output shot.png` gets a directory literally
+      // named `shot.png` — flag the likely mistake rather than silently doing it.
+      if (outputArg && extname(outputArg)) {
+        console.log(
+          `  note: --frames writes multiple pngs, so --output "${outputArg}" is a directory — frame-NNN.png files land inside it`,
+        )
+      }
+      mkdirSync(outDir, { recursive: true })
+      // clear stale frame-NNN.png from a prior run into the same dir — a
+      // shorter `--frames` count would otherwise leave higher-numbered frames
+      // behind, so the dir mixes two captures (F43). only frame-*.png is
+      // touched; any other files the caller put there are left alone.
+      for (const name of readdirSync(outDir)) {
+        if (/^frame-\d+\.png$/.test(name)) rmSync(join(outDir, name), { force: true })
+      }
+      console.log(`  sampling ${count} frames over ${durationSec}s → ${outDir}`)
+      const start: { ok: boolean; requestId?: number; error?: string } =
+        await bridge.send({
+          type: 'evaluate',
+          code: `window.__sootsimRecorder.startFrameCapture({ count: ${count}, durationMs: ${durationMs}${
+            layers ? `, layers: ${JSON.stringify(layers)}` : ''
+          } })`,
+        })
+      if (!start.ok || !start.requestId) {
+        console.error(`  frame capture start failed: ${start.error ?? 'unknown error'}`)
+        process.exit(1)
+      }
+      await new Promise((r) => setTimeout(r, durationMs))
+      const deadline = Date.now() + Math.max(5_000, durationMs)
+      let frames: Array<{ data: string; size: number }> | null = null
+      for (;;) {
+        const result: {
+          ok: boolean
+          done: boolean
+          frames?: Array<{ data: string; size: number }>
+          error?: string
+        } | null = await bridge.send({
+          type: 'evaluate',
+          code: `window.__sootsimRecorder.getFrameCaptureResult(${start.requestId})`,
+        })
+        if (!result) {
+          console.error('  frame capture result missing')
+          process.exit(1)
+        }
+        if (result.done) {
+          if (!result.ok) {
+            console.error(`  frame capture failed: ${result.error ?? 'unknown error'}`)
+            process.exit(1)
+          }
+          frames = result.frames ?? []
+          break
+        }
+        if (Date.now() >= deadline) {
+          console.error('  frame capture timed out')
+          process.exit(1)
+        }
+        await new Promise((r) => setTimeout(r, 100))
+      }
+      frames.forEach((f, i) => {
+        const p = `${outDir}/frame-${String(i + 1).padStart(3, '0')}.png`
+        writeFileSync(p, Buffer.from(f.data, 'base64'))
+      })
+      console.log(`  saved ${frames.length} frames`)
+      return
+    }
+
+    if (format === 'gif') {
+      const count = framesCount ?? Math.max(10, Math.round((durationSec * fps) / 3))
+      const out = resolveRecordingOutput(outputArg, `sootsim-${stamp()}.gif`)
+      mkdirSync(dirname(out), { recursive: true })
+      console.log(`  encoding gif: ${count} frames over ${durationSec}s → ${out}`)
+      const result: { data: string; size: number } | null = await evalCaptureStep(
+        bridge,
+        `window.__sootsimRecorder.captureGif({ frames: ${count}, durationMs: ${durationMs}${
+          maxWidth ? `, maxWidth: ${maxWidth}` : ''
+        }${layers ? `, layers: ${JSON.stringify(layers)}` : ''} })`,
+        'gif encode',
+        durationMs,
+      )
+      if (!result) {
+        console.error('  gif capture returned no frames')
+        process.exit(1)
+      }
+      writeFileSync(out, Buffer.from(result.data, 'base64'))
+      console.log(`  saved: ${out} (${formatBytes(result.size)})`)
+      return
+    }
+
+    // video path: webm or mp4
+    const out = resolveRecordingOutput(outputArg, `sootsim-${stamp()}.${format}`)
+    mkdirSync(dirname(out), { recursive: true })
+
+    const startOpts: {
+      format: string
+      fps: number
+      layers?: string
+      durationMs: number
+    } = {
+      format,
+      fps,
+      // thread the known duration so an abandoned recording's bitmap lock
+      // self-heals in ~duration+20s instead of the 8-min ceiling (F20-1).
+      durationMs,
+    }
+    if (layers) startOpts.layers = layers
+    const startResult: { ok: boolean; error?: string; format?: string } =
+      await evalCaptureStep(
+        bridge,
+        `window.__sootsimRecorder.start(${JSON.stringify(startOpts)})`,
+        `${format} start`,
+        durationMs,
+      )
+    if (!startResult.ok) {
+      console.error(`  start failed: ${startResult.error ?? 'unknown error'}`)
+      // a stale render-host streaming session is the usual cause — say how
+      // to recover instead of leaving the user staring at a bare error.
+      if (
+        /render host not available|already streaming|already recording|lock already held/i.test(
+          startResult.error ?? '',
+        )
+      ) {
+        console.error(
+          '  a prior recording was abandoned and its capture is still\n' +
+            '  releasing. retry in ~20s, or recover now with\n' +
+            '  `rnxsim close --sim <id>` then reopen the sim.',
+        )
+      }
+      process.exit(1)
+    }
+
+    console.log(`  recording ${format} for ${durationSec}s → ${out}`)
+    await new Promise((r) => setTimeout(r, durationMs))
+
+    const stopResult: {
+      ok: boolean
+      error?: string
+      size?: number
+      mime?: string
+      durationMs?: number
+      frameCount?: number
+    } = await evalCaptureStep(
+      bridge,
+      `window.__sootsimRecorder.stop()`,
+      `${format} encode/flush`,
+      durationMs,
+    )
+    if (!stopResult.ok) {
+      console.error(`  stop failed: ${stopResult.error ?? 'unknown error'}`)
+      process.exit(1)
+    }
+
+    if (!stopResult.size) {
+      console.error('  recorder returned an empty blob — nothing written')
+      process.exit(1)
+    }
+
+    await downloadBlob(bridge, out)
+    console.log(`  saved: ${out} (${formatBytes(stopResult.size)})`)
+    if (stopResult.durationMs && stopResult.frameCount !== undefined) {
+      console.log(
+        `  source frames: ${stopResult.frameCount} over ${(stopResult.durationMs / 1000).toFixed(2)}s ` +
+          `(${(stopResult.frameCount / (stopResult.durationMs / 1000)).toFixed(1)}fps)`,
+      )
+    }
+  } finally {
+    bridge.close()
+  }
+}
+
+// readiness probe with a short timeout. a sim can be registered with the
+// bridge yet never answer an `evaluate` — it loaded no app, or its page/worker
+// died. without the short cap the probe stalls the full recording timeout
+// (60s) before failing; cap it at 6s and fail fast with an actionable message.
+const SIM_PROBE_TIMEOUT_MS = 6_000
+async function probeSim(bridge: WsBridge, code: string): Promise<boolean> {
+  try {
+    return await bridge.send(
+      { type: 'evaluate', code },
+      { timeoutMs: SIM_PROBE_TIMEOUT_MS },
+    )
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    if (/^command timed out after \d+s$/.test(msg)) {
+      console.error(
+        '  sim did not respond — it is connected to the bridge but has not\n' +
+          '  loaded an app (or its page is unresponsive). run `rnxsim list`\n' +
+          '  and target a sim with a loaded app via --sim <id>.',
+      )
+      process.exit(1)
+    }
+    throw err
+  }
+}
+
+async function assertRecorderAvailable(bridge: WsBridge) {
+  const ok = await probeSim(bridge, 'typeof window.__sootsimRecorder !== "undefined"')
+  if (!ok) {
+    console.error(
+      '  window.__sootsimRecorder missing — is rnx engine running in this sim?',
+    )
+    process.exit(1)
+  }
+}
+
+// frame-capturing recordings (video / gif / png / combined) drive their
+// encoder off requestAnimationFrame and throttled timers, which browsers
+// clamp to ~1fps when the sootsim tab is hidden (backgrounded, or its chrome
+// window minimized). that silently produced a frozen-looking file and is
+// exactly why agents started pre-checking `document.hidden` by hand. refuse
+// up front with an actionable message instead. checkSimHealth already emits
+// the shared hidden-tab warning over the existing bridge probe (DRY — one
+// source for hidden detection); this only adds the hard stop. event-only
+// `live` recordings don't capture frames, so callers skip this guard there.
+async function assertTabVisibleForCapture(bridge: WsBridge) {
+  const { hidden } = await checkSimHealth(bridge)
+  if (hidden) {
+    console.error(
+      '  refusing to record: the rnx tab is hidden, so frame capture\n' +
+        '  would be throttled to ~1fps and produce a frozen-looking file.\n' +
+        '  bring the chrome window to the foreground (un-minimize / switch to\n' +
+        '  its tab) or run the recording in headless playwright, then retry.',
+    )
+    process.exit(1)
+  }
+}
+
+async function downloadBlob(bridge: WsBridge, outPath: string) {
+  // stream the blob back in chunks to avoid a single huge base64 payload
+  const chunks: Buffer[] = []
+  let offset = 0
+  while (true) {
+    const result: {
+      data: string
+      size: number
+      offset: number
+      done: boolean
+      mime: string
+    } | null = await bridge.send({
+      type: 'evaluate',
+      code: `window.__sootsimRecorder.getBlobBase64({ offset: ${offset}, chunk: ${
+        2 * 1024 * 1024
+      } })`,
+    })
+    if (!result) throw new Error('no blob available on recorder')
+    chunks.push(Buffer.from(result.data, 'base64'))
+    offset = result.offset
+    if (result.done) break
+  }
+  writeFileSync(outPath, Buffer.concat(chunks))
+}
+
+export function valueOf(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag)
+  if (idx < 0 || idx === args.length - 1) return undefined
+  return args[idx + 1]
+}
+
+export function extToFormat(path?: string): OutputFormat | undefined {
+  if (!path) return undefined
+  const ext = extname(path).toLowerCase().replace(/^\./, '')
+  if (ext === 'webm' || ext === 'mp4' || ext === 'gif') return ext as OutputFormat
+  if (ext === 'png') return 'png'
+  return undefined
+}
+
+export function resolveFormat(
+  formatArg: string | undefined,
+  outputArg: string | undefined,
+  framesCount: number | null,
+): OutputFormat {
+  if (formatArg) return formatArg as OutputFormat
+  if (framesCount != null) return 'png'
+  return extToFormat(outputArg) ?? 'webm'
+}
+
+function stamp(): string {
+  return new Date().toISOString().replace(/[:T]/g, '-').replace(/\..+/, '')
+}
+
+// default home for recordings when --output is omitted. writing into the
+// process cwd litters whatever directory the CLI was invoked from (the repo
+// root, most often) with sootsim-*.mp4 / sootsim-frames-*/ — F11-2. an
+// explicit --output still resolves relative to cwd as the caller expects.
+function recordingsDir(): string {
+  const dir = join(homedir(), '.sootsim', 'recordings')
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+function resolveRecordingOutput(
+  outputArg: string | undefined,
+  defaultName: string,
+): string {
+  return outputArg
+    ? resolve(process.cwd(), outputArg)
+    : join(recordingsDir(), defaultName)
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n}B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`
+  return `${(n / (1024 * 1024)).toFixed(2)}MB`
+}
+
+interface RecordingState {
+  simId: string | null
+  mode: RecordMode
+  format: 'webm' | 'mp4'
+  fps: number
+  layers?: 'tenant' | 'shell'
+  startedAt: string
+}
+
+function parseMode(raw: string | undefined): RecordMode {
+  if (!raw) return 'video'
+  if (raw === 'video' || raw === 'live' || raw === 'combined') return raw
+  console.error(`  invalid --mode "${raw}" — expected video | live | combined`)
+  process.exit(1)
+}
+
+function recordingStatePath(): string {
+  return join(tmpdir(), `sootsim-recording-${getCliIdentityKey()}.json`)
+}
+
+function readRecordingState(): RecordingState | null {
+  const p = recordingStatePath()
+  if (!existsSync(p)) return null
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8')) as Partial<RecordingState>
+    // default mode for state files written before --mode existed
+    return { mode: 'video', ...parsed } as RecordingState
+  } catch {
+    rmSync(p, { force: true })
+    return null
+  }
+}
+
+function writeRecordingState(state: RecordingState) {
+  writeFileSync(recordingStatePath(), JSON.stringify(state, null, 2))
+}
+
+function clearRecordingState() {
+  rmSync(recordingStatePath(), { force: true })
+}
+
+// the record state file is global — keyed by CLI identity, not per-sim — so
+// `status`/`stop`/`cancel` act on whichever `record start` session exists
+// regardless of --sim. when the caller targets a different sim than the one
+// the session was started on, say so instead of silently reporting/stopping
+// another sim's recording (F11-1).
+function noteSimMismatch(
+  requestedSimId: string | null | undefined,
+  state: RecordingState,
+) {
+  if (requestedSimId && state.simId && requestedSimId !== state.simId) {
+    console.log(
+      `  note: the tracked recording session is on sim ${state.simId}, not the\n` +
+        `  requested sim ${requestedSimId}. record state is global (not per-sim);\n` +
+        `  this command acts on that session regardless of --sim.`,
+    )
+  }
+}
+
+async function recordStart(args: string[], opts: RecordOptions) {
+  const existing = readRecordingState()
+  if (existing) {
+    console.error(
+      `  recording already in progress (started ${existing.startedAt}, sim ${existing.simId ?? '?'}). run \`rnxsim record stop\` first, or \`rnxsim record cancel\` to discard.`,
+    )
+    process.exit(1)
+  }
+
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    stripBooleanFlags: ['--no-shell', '--shell-only', '--lockstep'],
+    stripValueFlags: [
+      '--mode',
+      '--fps',
+      '--format',
+      '--max-width',
+      '--origin',
+      '--owner',
+      '--repo',
+    ],
+  })
+  const mode = parseMode(valueOf(args, '--mode'))
+  const layers: 'tenant' | 'shell' | undefined = args.includes('--shell-only')
+    ? 'shell'
+    : args.includes('--no-shell')
+      ? 'tenant'
+      : undefined
+  const formatArg = valueOf(args, '--format') as OutputFormat | undefined
+  const format = formatArg === 'mp4' ? 'mp4' : 'webm'
+  if (formatArg && format !== formatArg) {
+    console.error(
+      `  record start only supports webm or mp4 (got: ${formatArg}). for gif/png use atomic mode: rnxsim record --format ${formatArg} --duration <s>`,
+    )
+    process.exit(1)
+  }
+  const fps = Number(valueOf(args, '--fps') ?? '30')
+  const repoScope = readRepoScope(args)
+
+  const bridge = createBridgeFromParsed({
+    ...parsed,
+    commandTimeoutMs:
+      mode === 'live' || mode === 'combined' ? STORE_RECORD_START_TIMEOUT_MS : 15_000,
+  })
+  try {
+    if (mode === 'live' || mode === 'combined') {
+      // live mode captures events only — --no-shell / --shell-only have no
+      // video to act on there (F12-1).
+      if (layers && mode === 'live') {
+        console.log(
+          `  note: --${layers === 'shell' ? 'shell-only' : 'no-shell'} is ignored for --mode live — live recordings capture events only, no video`,
+        )
+      }
+      // only upload-bearing modes hit the cloud — gate the recording
+      // entitlement here, not on local-file webm/mp4 capture (F19).
+      // allowGitHubAuth: the PR-preview runner (`record start --mode
+      // combined`) authenticates with a GitHub installation token, not
+      // RNX_API_KEY — the whole pipeline is zero-secrets by design.
+      // mirrors `flow --record`. the bypass only triggers for github-kind
+      // auth (CI); local paid users still hit the billing check.
+      await ensureCliRecordingEntitlement('record', {
+        originOverride: valueOf(args, '--origin'),
+        allowGitHubAuth: true,
+      })
+      await assertStoreBridgesAvailable(bridge)
+      await assertGuestBundleLoaded(bridge, mode)
+      if (mode === 'combined') await assertTabVisibleForCapture(bridge)
+      await injectPreviewSessionAuth(bridge, valueOf(args, '--origin'), repoScope)
+      const started = await evalStoreStart(
+        bridge,
+        mode,
+        mode === 'combined' ? layers : undefined,
+      )
+      if (!started.ok) {
+        console.error(
+          `  start failed: recording store refused to start (${mode})` +
+            (started.error ? `: ${started.error}` : ''),
+        )
+        process.exit(1)
+      }
+    } else {
+      await assertRecorderAvailable(bridge)
+      await assertTabVisibleForCapture(bridge)
+      const lockstep = args.includes('--lockstep')
+      if (lockstep && format !== 'mp4') {
+        console.error('  --lockstep requires --format mp4 (webm is realtime-clocked)')
+        process.exit(1)
+      }
+      const startOpts: {
+        format: string
+        fps: number
+        layers?: string
+        lockstep?: boolean
+      } = { format, fps }
+      if (layers) startOpts.layers = layers
+      if (lockstep) startOpts.lockstep = true
+      const result: { ok: boolean; error?: string } = await bridge.send({
+        type: 'evaluate',
+        code: `window.__sootsimRecorder.start(${JSON.stringify(startOpts)})`,
+      })
+      if (!result.ok) {
+        console.error(`  start failed: ${result.error ?? 'unknown error'}`)
+        process.exit(1)
+      }
+    }
+    writeRecordingState({
+      simId: parsed.simId ?? null,
+      mode,
+      format,
+      fps,
+      layers,
+      startedAt: new Date().toISOString(),
+    })
+    if (mode === 'video') {
+      console.log(
+        `  recording ${format} @ ${fps}fps${layers ? ` (${layers})` : ''} — run \`rnxsim record stop --output <path>\` when done`,
+      )
+    } else {
+      console.log(
+        `  recording ${mode} — run \`rnxsim record stop\` when done (add --open to launch the preview URL)`,
+      )
+    }
+  } finally {
+    bridge.close()
+  }
+}
+
+async function recordPreludeStart(args: string[], opts: RecordOptions) {
+  const existing = readRecordingState()
+  if (existing) {
+    console.error(
+      `  recording already in progress (started ${existing.startedAt}, sim ${existing.simId ?? '?'}). run \`rnxsim record stop\` first, or \`rnxsim record cancel\` to discard.`,
+    )
+    process.exit(1)
+  }
+
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    stripBooleanFlags: [],
+    stripValueFlags: ['--origin'],
+  })
+  const bridge = createBridgeFromParsed({ ...parsed, commandTimeoutMs: 15_000 })
+  try {
+    await assertStoreBridgesAvailable(bridge)
+    await assertTabVisibleForCapture(bridge)
+    const ok: boolean = await bridge.send({
+      type: 'evaluate',
+      code: `(() => {
+        const start = window.SootSim?.bridges?.startRecordingPrelude
+        if (typeof start !== 'function') return false
+        return Promise.resolve(start()).then((value) => value === true)
+      })()`,
+    })
+    if (!ok) {
+      const reason = await bridge
+        .send({
+          type: 'evaluate',
+          code: `(() => {
+            const getError = window.SootSim?.bridges?.getRecordingStartError
+            return typeof getError === 'function' ? getError() : null
+          })()`,
+        })
+        .catch(() => null)
+      console.error(
+        `  prelude start failed: recording store refused to start${
+          typeof reason === 'string' && reason ? ` (${reason})` : ''
+        }`,
+      )
+      process.exit(1)
+    }
+    console.log(
+      '  recording preview prelude — run `rnxsim record start --mode combined` when the visible proof segment is ready',
+    )
+  } finally {
+    bridge.close()
+  }
+}
+
+// query the engine for the *actual* recording state. the local state file
+// only tracks `record start` sessions — an atomic `record --duration` run
+// or the in-browser record button records without writing it. probing the
+// engine lets `status`/`cancel` report the truth instead of lying "no
+// recording in progress" while one is plainly running (F52).
+//
+// two independent recorder surfaces exist and must both be checked:
+//   - the recording store (`SootSim.bridges.getRecordingState`) drives
+//     live/combined preview-share recordings
+//   - the headless recorder (`__sootsimRecorder`) drives atomic video/gif/
+//     png capture — its state lives on a separate `active` flag
+//   - the event recorder alone drives hidden PR-preview preludes before a
+//     visible live/combined segment exists
+// returns null when the engine can't be reached.
+type EngineRecordingState = 'idle' | 'recording' | 'processing' | 'prelude'
+
+async function probeEngineRecordingState(
+  bridge: WsBridge,
+): Promise<EngineRecordingState | null> {
+  try {
+    const snap: { store?: string; headless?: string; eventRecording?: boolean } | null =
+      await bridge.send({
+        type: 'evaluate',
+        code: `(() => {
+        const store = window.SootSim?.bridges?.getRecordingState?.();
+        const headless = window.__sootsimRecorder?.state?.();
+        const eventRecorder = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder;
+        const eventRecording =
+          typeof eventRecorder?.isRecording === 'function'
+            ? eventRecorder.isRecording() === true
+            : false;
+        return { store: store ? store.state : undefined, headless, eventRecording };
+      })()`,
+      })
+    if (!snap) return null
+    if (snap.store === 'recording' || snap.headless === 'recording') return 'recording'
+    if (snap.store === 'processing') return 'processing'
+    if (snap.eventRecording) return 'prelude'
+    if (snap.store === 'idle' || snap.headless === 'idle') return 'idle'
+    return null
+  } catch {
+    return null
+  }
+}
+
+async function cancelEngineRecording(bridge: WsBridge): Promise<{
+  store: boolean
+  headless: boolean
+}> {
+  const storeCanceled: boolean = await bridge
+    .send({
+      type: 'evaluate',
+      code: `(() => {
+        const store = window.SootSim?.bridges?.getRecordingState?.();
+        const eventRecorder = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder;
+        const hadStoreRecording = store && store.state !== 'idle';
+        const hadEventRecording =
+          typeof eventRecorder?.isRecording === 'function'
+            ? eventRecorder.isRecording() === true
+            : false;
+        const cancel = window.SootSim?.bridges?.cancelRecording;
+        if (typeof cancel === 'function') cancel();
+        return Boolean(hadStoreRecording || hadEventRecording);
+      })()`,
+    })
+    .catch(() => false)
+  const headlessCanceled: boolean = await bridge
+    .send({
+      type: 'evaluate',
+      code: `(async () => {
+        const r = window.__sootsimRecorder;
+        if (r && typeof r.forceRelease === 'function') return await r.forceRelease();
+        return false;
+      })()`,
+    })
+    .catch(() => false)
+  return { store: storeCanceled, headless: headlessCanceled }
+}
+
+async function recordStatus(args: string[], opts: RecordOptions) {
+  const state = readRecordingState()
+  if (state) {
+    noteSimMismatch(parseBridgeCliArgs(args, { port: opts.port }).simId, state)
+    if (state.mode === 'video') {
+      console.log(
+        `  recording ${state.mode} (${state.format} @ ${state.fps}fps) on sim ${state.simId ?? '?'} since ${state.startedAt}`,
+      )
+    } else {
+      console.log(
+        `  recording ${state.mode} on sim ${state.simId ?? '?'} since ${state.startedAt}`,
+      )
+    }
+    return
+  }
+  // no `record start` session — but an atomic run or the rail button may
+  // still be recording. ask the engine before claiming nothing is happening.
+  const parsed = parseBridgeCliArgs(args, { port: opts.port })
+  const bridge = createBridgeFromParsed({ ...parsed, commandTimeoutMs: 8_000 })
+  try {
+    const engineState = await probeEngineRecordingState(bridge)
+    if (
+      engineState === 'recording' ||
+      engineState === 'processing' ||
+      engineState === 'prelude'
+    ) {
+      if (engineState === 'prelude') {
+        console.log(
+          '  a recording preview prelude is active. hidden setup is being\n' +
+            '  captured for the next live/combined preview recording. finish\n' +
+            '  it with `rnxsim record start --mode combined`, or discard it\n' +
+            '  with `rnxsim record cancel`.',
+        )
+        return
+      }
+      console.log(
+        `  a recording is in progress (engine state: ${engineState}), but not via\n` +
+          '  `record start` — it was started by an atomic `record --duration`\n' +
+          '  run or the in-browser record button, which own their own lifecycle.\n' +
+          '  if that controlling run is still alive it will finish on its own\n' +
+          '  (atomic `--mode video/gif/png` writes a local file from that\n' +
+          '  process; live/combined upload to /preview/<id>). if the run was\n' +
+          '  killed, the recording is abandoned and will NOT finish — reclaim\n' +
+          '  it now with `rnxsim record cancel`, or it auto-reclaims when the\n' +
+          "  abandoned capture's deadline lapses.",
+      )
+    } else {
+      console.log('  no recording in progress')
+    }
+  } finally {
+    bridge.close()
+  }
+}
+
+async function recordCancel(args: string[], opts: RecordOptions) {
+  const state = readRecordingState()
+  if (!state) {
+    // no `record start` session to cancel — but check the engine so we
+    // don't falsely claim nothing is happening while an atomic run records.
+    const probeParsed = parseBridgeCliArgs(args, { port: opts.port })
+    const probeBridge = createBridgeFromParsed({
+      ...probeParsed,
+      commandTimeoutMs: 8_000,
+    })
+    try {
+      const engineState = await probeEngineRecordingState(probeBridge)
+      if (
+        engineState === 'recording' ||
+        engineState === 'processing' ||
+        engineState === 'prelude'
+      ) {
+        // `record cancel` is explicit intent: the caller wants whatever is
+        // recording gone. force-reclaim the headless/store recorder rather
+        // than refusing and telling them to wait out the deadline (QA
+        // F22-1). this also un-wedges live/combined, which the killed
+        // atomic `--mode video` bitmap lock was blocking.
+        const reclaimed = await cancelEngineRecording(probeBridge)
+        if (reclaimed.store && engineState === 'prelude') {
+          console.log('  recording preview prelude cancelled')
+        } else if (reclaimed.store || reclaimed.headless) {
+          console.log(
+            '  reclaimed an abandoned recording (started by an atomic\n' +
+              '  `record --duration` run or the record button whose owner is\n' +
+              '  gone). the recorder is idle again — live/combined can start.',
+          )
+        } else {
+          console.log(
+            '  a recording is in progress and still owned by a live atomic\n' +
+              '  `record --duration` run or the in-browser record button — it\n' +
+              '  will finish on its own and nothing was reclaimed.',
+          )
+        }
+      } else {
+        console.log('  no recording in progress')
+      }
+    } finally {
+      probeBridge.close()
+    }
+    return
+  }
+  const parsed = parseBridgeCliArgs(args, { port: opts.port })
+  noteSimMismatch(parsed.simId, state)
+  // the recorder (and its buffered blob) lives in the page of the sim the
+  // recording was *started* on — `state.simId` wins over the requested
+  // --sim, otherwise cancel would stop an idle recorder on the wrong sim
+  // and leave the real recording running (F11-1).
+  const simId = state.simId ?? parsed.simId ?? undefined
+  const bridge = createBridgeFromParsed({
+    ...parsed,
+    simId,
+    commandTimeoutMs: 15_000,
+  })
+  try {
+    if (state.mode === 'live' || state.mode === 'combined') {
+      await bridge.send({
+        type: 'evaluate',
+        code: `void window.SootSim?.bridges?.cancelRecording?.()`,
+      })
+    } else {
+      await bridge.send({
+        type: 'evaluate',
+        code: `window.__sootsimRecorder.stop()`,
+      })
+    }
+  } catch {
+    // best-effort — always clear local state
+  } finally {
+    clearRecordingState()
+    bridge.close()
+  }
+  console.log('  recording cancelled')
+}
+
+async function recordStop(args: string[], opts: RecordOptions) {
+  const state = readRecordingState()
+  if (!state) {
+    console.error('  no recording in progress. start one with `rnxsim record start`.')
+    process.exit(1)
+  }
+
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    stripBooleanFlags: ['--open'],
+    stripValueFlags: ['--output'],
+  })
+  noteSimMismatch(parsed.simId, state)
+  // the recorder + buffered blob live in the sim the recording was started
+  // on — route there, not to the requested --sim, or stop would drain an
+  // idle recorder on the wrong sim and lose the capture (F11-1).
+  const simId = state.simId ?? parsed.simId ?? undefined
+  const openAfter = args.includes('--open')
+
+  const bridge = createBridgeFromParsed({
+    ...parsed,
+    simId,
+    commandTimeoutMs:
+      state.mode === 'live' || state.mode === 'combined' ? UPLOAD_TIMEOUT_MS : 60_000,
+  })
+  try {
+    if (state.mode === 'live' || state.mode === 'combined') {
+      await evalStoreStop(bridge)
+      const result = await pollStoreUpload(bridge)
+      clearRecordingState()
+      handleStoreUploadResult(result, openAfter, state.mode)
+      return
+    }
+
+    const outputArg = valueOf(args, '--output')
+    const out = resolveRecordingOutput(outputArg, `sootsim-${stamp()}.${state.format}`)
+    mkdirSync(dirname(out), { recursive: true })
+    const stopResult: {
+      ok: boolean
+      error?: string
+      size?: number
+      mime?: string
+      durationMs?: number
+      frameCount?: number
+    } = await bridge.send({
+      type: 'evaluate',
+      code: `window.__sootsimRecorder.stop()`,
+    })
+    if (!stopResult.ok) {
+      console.error(`  stop failed: ${stopResult.error ?? 'unknown error'}`)
+      clearRecordingState()
+      process.exit(1)
+    }
+    if (!stopResult.size) {
+      console.error('  recorder returned an empty blob — nothing written')
+      clearRecordingState()
+      process.exit(1)
+    }
+    await downloadBlob(bridge, out)
+    clearRecordingState()
+    console.log(`  saved: ${out} (${formatBytes(stopResult.size)})`)
+    if (stopResult.durationMs && stopResult.frameCount !== undefined) {
+      console.log(
+        `  source frames: ${stopResult.frameCount} over ${(stopResult.durationMs / 1000).toFixed(2)}s ` +
+          `(${(stopResult.frameCount / (stopResult.durationMs / 1000)).toFixed(1)}fps)`,
+      )
+    }
+  } finally {
+    bridge.close()
+  }
+}
+
+// ─── store-backed recording helpers (live / combined) ─────────────────────
+
+async function assertStoreBridgesAvailable(bridge: WsBridge) {
+  const ok = await probeSim(
+    bridge,
+    'typeof window.SootSim?.bridges?.startRecording === "function" && typeof window.SootSim?.bridges?.stopRecording === "function"',
+  )
+  if (!ok) {
+    console.error(
+      '  SootSim.bridges.startRecording missing — is rnx engine running in this sim?',
+    )
+    process.exit(1)
+  }
+}
+
+// CLI-driven live/combined recording runs in a headless browser that was
+// never logged in, so browser-side upload has no bearer. push the CLI's own
+// auth — the same RNX_API_KEY / `sootsim login` / GitHub token
+// ensureCliRecordingEntitlement just verified — into the page's shared-session
+// store before starting. GitHub PR-preview auth also needs its repo identity
+// in the upload init body so the server treats the bearer as a GitHub upload
+// rather than a contrast user session.
+// combined/live recordings upload the guest bundle to /preview/<id> so the
+// page can replay the app. a built-in shell app (photos, settings, the home
+// grid) has no guest bundle — `uploadLivePreview` only discovers this at the
+// END and throws "no bundle loaded" *after* the full timed recording already
+// ran (QA F19-3). probe the same `__sootsimCaptureBundle` snapshot the upload
+// uses, up front, and fail fast with an actionable message instead.
+async function assertGuestBundleLoaded(bridge: WsBridge, mode: RecordMode) {
+  const hasBundle = await probeSim(
+    bridge,
+    `(() => {
+      const fn = window.__sootsimCaptureBundle
+      if (typeof fn !== 'function') return false
+      const snap = fn()
+      return !!(snap && snap.bundleUrl)
+    })()`,
+  )
+  if (!hasBundle) {
+    console.error(
+      `  --mode ${mode} needs a guest app bundle to upload to /preview/<id>,\n` +
+        `  but this sim has no bundle loaded (a built-in shell screen like\n` +
+        `  photos/settings/home has none). open a metro/guest app first, or\n` +
+        `  use \`--mode video\` for a local screen recording with no upload.`,
+    )
+    process.exit(1)
+  }
+}
+
+async function injectPreviewSessionAuth(
+  bridge: WsBridge,
+  originOverride?: string,
+  repoScope?: RepoScope,
+): Promise<void> {
+  const auth = resolveCliAuth()
+  // ensureCliRecordingEntitlement already exits the process when auth is
+  // missing — this guard is purely defensive.
+  if (!auth) return
+  const token = auth.kind === 'api-key' ? auth.secret : auth.token
+  const provenance = resolveRunProvenance()
+  const gitContext = {
+    branch: provenance.branch ?? undefined,
+    commitSha: provenance.commitSha ?? undefined,
+    githubUsername: provenance.githubUsername ?? undefined,
+    pullRequestNumber: provenance.pullRequestNumber ?? undefined,
+    pullRequestTitle: provenance.pullRequestTitle ?? undefined,
+  }
+  const uploadIdentity =
+    auth.kind === 'github'
+      ? {
+          ...githubUploadIdentity(auth),
+          owner: repoScope?.owner,
+          repo: repoScope?.repo,
+          ...gitContext,
+        }
+      : repoScope
+        ? {
+            owner: repoScope.owner,
+            repo: repoScope.repo,
+            ...gitContext,
+          }
+        : null
+  const uploadOrigin = originOverride ? originOverride.replace(/\/$/, '') : null
+  const ok: boolean = await bridge.send({
+    type: 'evaluate',
+    code: `(() => {
+      const set = window.SootSim && window.SootSim.bridges && window.SootSim.bridges.setSession
+      if (typeof set !== 'function') return false
+      set({ token: ${JSON.stringify(token)}, user: null })
+      window.__sootsimPreviewUploadIdentity = ${JSON.stringify(uploadIdentity)}
+      window.__sootsimPreviewUseInjectedBearer = true
+      ${
+        uploadOrigin
+          ? `window.__sootsimUploadOrigin = ${JSON.stringify(uploadOrigin)}`
+          : 'delete window.__sootsimUploadOrigin'
+      }
+      return true
+    })()`,
+  })
+  if (!ok) {
+    // the usual cause is a stale tab — a sim that connected before the
+    // engine was rebuilt keeps the old bundle until it reloads. an actually
+    // outdated install is the rarer case, so lead with the cheap fix.
+    console.error(
+      '  SootSim.bridges.setSession missing — this sim is running an engine\n' +
+        '  build without CLI-injected preview auth. reload the sim or open a\n' +
+        '  fresh one (`rnxsim open --new`); if it persists, update rnx.',
+    )
+    process.exit(1)
+  }
+}
+
+async function evalStoreStart(
+  bridge: WsBridge,
+  mode: RecordMode,
+  layers?: 'tenant' | 'shell',
+): Promise<{ ok: boolean; error: string | null }> {
+  // the CLI already made the entitlement/auth decision before entering the
+  // engine. pass that explicit fact through so GitHub PR-preview auth is not
+  // rejected by the browser-session billing gate.
+  const layersArg = layers ? JSON.stringify(layers) : 'undefined'
+  const ok: boolean = await bridge.send({
+    type: 'evaluate',
+    code: `window.SootSim.bridges.startRecording(${JSON.stringify(mode)}, ${layersArg}, { skipEntitlement: true })`,
+  })
+  if (ok === true) return { ok: true, error: null }
+  // the engine knows exactly why it refused — read the structured reason
+  // back so the operator (and the PR-preview agent) sees it instead of an
+  // opaque "recording store refused to start".
+  const error: string | null = await bridge
+    .send({
+      type: 'evaluate',
+      code: `(window.SootSim?.bridges?.getRecordingStartError?.() ?? null)`,
+    })
+    .catch(() => null)
+  return { ok: false, error: error ?? null }
+}
+
+async function evalStoreStop(bridge: WsBridge): Promise<void> {
+  await bridge.send({
+    type: 'evaluate',
+    code: `void window.SootSim.bridges.stopRecording()`,
+  })
+}
+
+interface StoreUploadResult {
+  previewUrl?: string
+  uploadError?: string
+  eventCount?: number
+}
+
+async function pollStoreUpload(bridge: WsBridge): Promise<StoreUploadResult> {
+  const deadline = Date.now() + UPLOAD_TIMEOUT_MS
+  while (Date.now() < deadline) {
+    const snap: {
+      state: 'idle' | 'recording' | 'processing'
+      lastUpload: { previewUrl?: string; eventCount?: number } | null
+      uploadError: string | null
+    } | null = await bridge.send({
+      type: 'evaluate',
+      code: `(() => { const s = window.SootSim?.bridges?.getRecordingState?.(); return s ? { state: s.state, lastUpload: s.lastUpload, uploadError: s.uploadError } : null })()`,
+    })
+    if (snap && snap.state === 'idle') {
+      if (snap.uploadError) return { uploadError: snap.uploadError }
+      if (snap.lastUpload?.previewUrl) {
+        return {
+          previewUrl: snap.lastUpload.previewUrl,
+          eventCount: snap.lastUpload.eventCount,
+        }
+      }
+    }
+    await new Promise((r) => setTimeout(r, 300))
+  }
+  return { uploadError: `upload did not settle within ${UPLOAD_TIMEOUT_MS / 1000}s` }
+}
+
+function handleStoreUploadResult(
+  result: StoreUploadResult,
+  openAfter: boolean,
+  mode: RecordMode,
+) {
+  if (result.uploadError) {
+    console.error(`  upload failed: ${result.uploadError}`)
+    process.exit(1)
+  }
+  if (!result.previewUrl) {
+    console.error('  upload returned no preview URL')
+    process.exit(1)
+  }
+  console.log(`  preview: ${result.previewUrl}`)
+  // the preview id is content-addressed (shareId = hash of the bundle), so
+  // re-recording the *same* app bundle deliberately reuses this URL and
+  // replaces the prior capture there — this is how stable demo shares work.
+  // it's intentional, but it was silent: a quick throwaway re-record could
+  // clobber a good earlier capture at a URL someone already shared, with no
+  // warning (QA F19-4). say so once so the reuse is a known choice.
+  console.log(
+    '  note: this URL is content-addressed — re-recording the same bundle\n' +
+      '  replaces this capture at the same /preview/<id>.',
+  )
+  // surface how many interaction events were captured (F14-7). without this
+  // the CLI gave no signal that an event-capture regression shipped a stale
+  // or empty stream — the only tell was opening the preview and watching
+  // replay come up short.
+  if ((mode === 'live' || mode === 'combined') && typeof result.eventCount === 'number') {
+    console.log(
+      `  captured ${result.eventCount} event${result.eventCount === 1 ? '' : 's'}`,
+    )
+  }
+  // a recording with no captured events uploads a valid share, but the
+  // preview page's Live tab has nothing to replay — it just boots a fresh
+  // interactive session, which reads as a broken link. say so rather than
+  // letting the user discover it after sharing (F50). combined recordings
+  // still have a playable Video tab, but Live has no action stream.
+  if ((mode === 'live' || mode === 'combined') && result.eventCount === 0) {
+    if (mode === 'combined') {
+      console.log(
+        '  note: this combined recording captured no events — the Live tab has\n' +
+          '  nothing to replay. Video will play the captured screen recording.',
+      )
+    } else {
+      console.log(
+        '  note: this live recording captured no events — the preview has nothing\n' +
+          '  to replay and will boot a fresh interactive session instead.',
+      )
+    }
+  }
+  if (openAfter) {
+    void openUrl(result.previewUrl)
+  }
+}