peachsim 0.1.527

package/cli/commands/cpu-profile.ts

@@ -0,0 +1,941 @@
+// rnx perf cpu — capture sampled CPU traces from the page and every worker.
+//
+// the JS Self-Profiler API (`new Profiler()`) cannot be constructed in a
+// dedicated-worker scope, and rnx runs the guest app in the tenant worker,
+// so the old in-worker approach was unsupported (F28). this implementation
+// attaches Chromium's `Profiler` CDP domain to the page and worker targets —
+// which returns the .cpuprofile shape directly for every execution context.
+//
+// dedicated workers are not top-level CDP targets, so we connect to the page
+// target, `Target.setAutoAttach` to discover the worker child sessions, and
+// route `Profiler.*` to each worker via its sessionId (flatten mode).
+//
+// the user's normal rnx tab runs in plain Chrome without a debug port.
+// the easiest way to get a profilable sim is to open one with a CDP port —
+// it stays driveable over the WS bridge, so you can scroll/navigate while
+// profiling (the playwright driver passes --remote-debugging-port through):
+//
+//   rnx open <metro-port> --new --driver playwright --cdp-port 9222
+//   rnx perf cpu --cdp-port 9222 --match <metro-port> --duration 5
+//
+// (a standalone CDP Chrome also works for profiling a static page, but it
+// does NOT register on the bridge, so it can't be driven — see printNoCdp.)
+//
+// interact with the app during the capture window. the reference probe that
+// also drives the interaction itself lives at
+// scripts/debug/cdp-worker-cpu-profile.ts.
+
+import { createHash } from 'node:crypto'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { WebSocket } from 'ws'
+import { getCliVersion } from '../../src/cli-version'
+import { IS_STANDALONE } from '../standalone'
+
+interface ProfileOptions {
+  port?: number
+  verbose?: boolean
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+// compact CDP client with flatten-mode sessionId routing — one ws to the page
+// target carries the page session plus every auto-attached worker session.
+class Cdp {
+  private ws: WebSocket
+  private nextId = 1
+  private pending = new Map<
+    number,
+    {
+      res: (v: any) => void
+      rej: (e: any) => void
+      timeout: ReturnType<typeof setTimeout>
+    }
+  >()
+  private listeners = new Set<(method: string, params: any, sessionId?: string) => void>()
+  private ready: Promise<void>
+
+  constructor(wsUrl: string) {
+    this.ws = new WebSocket(wsUrl, { maxPayload: 1 << 28 })
+    this.ready = new Promise((res, rej) => {
+      this.ws.once('open', () => res())
+      this.ws.once('error', rej)
+    })
+    this.ws.on('message', (data) => {
+      const msg = JSON.parse(data.toString())
+      if (msg.id && this.pending.has(msg.id)) {
+        const { res, rej, timeout } = this.pending.get(msg.id)!
+        this.pending.delete(msg.id)
+        clearTimeout(timeout)
+        msg.error ? rej(new Error(JSON.stringify(msg.error))) : res(msg.result)
+      } else if (msg.method) {
+        for (const l of this.listeners) l(msg.method, msg.params, msg.sessionId)
+      }
+    })
+    this.ws.on('close', () => {
+      for (const [id, request] of this.pending) {
+        clearTimeout(request.timeout)
+        request.rej(new Error(`CDP connection closed with request ${id} pending`))
+      }
+      this.pending.clear()
+    })
+  }
+
+  waitOpen() {
+    return this.ready
+  }
+
+  on(l: (method: string, params: any, sessionId?: string) => void) {
+    this.listeners.add(l)
+  }
+
+  send(
+    method: string,
+    params: Record<string, unknown> = {},
+    sessionId?: string,
+  ): Promise<any> {
+    const id = this.nextId++
+    return new Promise((res, rej) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id)
+        rej(new Error(`CDP ${method} timed out after 5s`))
+      }, 5_000)
+      this.pending.set(id, { res, rej, timeout })
+      this.ws.send(
+        JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }),
+      )
+    })
+  }
+
+  close() {
+    try {
+      this.ws.close()
+    } catch {}
+  }
+}
+
+interface CdpTarget {
+  type: string
+  title?: string
+  url: string
+  webSocketDebuggerUrl: string
+}
+
+interface AttachedTarget {
+  attachedAtMs: number
+  detached: boolean
+  detachedAtMs?: number
+  error?: string
+  profile?: any
+  profileStartedAtMs?: number
+  profileStoppedAtMs?: number
+  role: string
+  sessionId?: string
+  started: boolean
+  title: string
+  type: string
+  url: string
+}
+
+export interface CpuProfileInteractionBarrier {
+  marker: string
+  reachedAtEpochMs: number
+  releasedBy: string
+  releasedAtEpochMs: number
+}
+
+export interface CpuProfileCoverage {
+  coverageMs: number
+  coverageRatio: number
+  startedOffsetMs: number | null
+  stoppedOffsetMs: number | null
+}
+
+export interface CpuProfileBrowserExecutableIdentity {
+  path: string
+  sha256: string
+}
+
+export interface CpuProfileBrowserIdentity {
+  name: string
+  version: string
+  executable: CpuProfileBrowserExecutableIdentity
+}
+
+export interface CpuProfileCaptureEvidence {
+  label: string
+  actionEpochMs: number
+}
+
+export interface CpuProfileWorkloadIdentity {
+  scenario: string
+  sourceSha256: string
+}
+
+export interface CpuProfileWorkloadEvidence {
+  browserIdentity: CpuProfileBrowserIdentity
+  captures: CpuProfileCaptureEvidence[]
+  completionMarker: string
+  expectedCaptureLabels: string[]
+  runtimeIdentity: Record<string, unknown>
+  stage: string
+  workloadIdentity: CpuProfileWorkloadIdentity
+}
+
+export function cpuProfileCoverage(
+  profileStartedAtMs: number | undefined,
+  profileStoppedAtMs: number | undefined,
+  windowStartedAtMs: number,
+  windowEndedAtMs: number,
+): CpuProfileCoverage {
+  const requestedMs = Math.max(0, windowEndedAtMs - windowStartedAtMs)
+  if (
+    profileStartedAtMs === undefined ||
+    profileStoppedAtMs === undefined ||
+    requestedMs === 0
+  ) {
+    return {
+      coverageMs: 0,
+      coverageRatio: 0,
+      startedOffsetMs:
+        profileStartedAtMs === undefined ? null : profileStartedAtMs - windowStartedAtMs,
+      stoppedOffsetMs:
+        profileStoppedAtMs === undefined ? null : profileStoppedAtMs - windowStartedAtMs,
+    }
+  }
+  const coverageMs = Math.max(
+    0,
+    Math.min(profileStoppedAtMs, windowEndedAtMs) -
+      Math.max(profileStartedAtMs, windowStartedAtMs),
+  )
+  return {
+    coverageMs,
+    coverageRatio: coverageMs / requestedMs,
+    startedOffsetMs: profileStartedAtMs - windowStartedAtMs,
+    stoppedOffsetMs: profileStoppedAtMs - windowStartedAtMs,
+  }
+}
+
+export function cpuProfileRoleLabels(
+  targets: readonly { captured: boolean; role: string }[],
+): string[] {
+  const labels = new Array<string>(targets.length)
+  const roleCounts = new Map<string, number>()
+  const assign = (index: number) => {
+    const role = targets[index].role
+    const count = (roleCounts.get(role) ?? 0) + 1
+    roleCounts.set(role, count)
+    labels[index] = count === 1 ? role : `${role}-${count}`
+  }
+  for (let index = 0; index < targets.length; index++) {
+    if (targets[index].captured) assign(index)
+  }
+  for (let index = 0; index < targets.length; index++) {
+    if (!targets[index].captured) assign(index)
+  }
+  return labels
+}
+
+export function cpuProfileTargetOverlapsWindow(
+  detachedAtMs: number | undefined,
+  windowStartedAtMs: number,
+): boolean {
+  return detachedAtMs === undefined || detachedAtMs > windowStartedAtMs
+}
+
+export function cpuProfileActionsWithinWindow(
+  actionEpochMs: readonly number[],
+  windowStartedAtEpochMs: number,
+  windowEndedAtEpochMs: number,
+): boolean {
+  return (
+    actionEpochMs.length > 0 &&
+    actionEpochMs.every(
+      (epochMs) =>
+        Number.isFinite(epochMs) &&
+        epochMs >= windowStartedAtEpochMs &&
+        epochMs <= windowEndedAtEpochMs,
+    )
+  )
+}
+
+function cpuProfileRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return Object.fromEntries(Object.entries(value))
+}
+
+function cpuProfileNonemptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0
+}
+
+function cpuProfileSha256(value: unknown): value is string {
+  return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value)
+}
+
+function cpuProfileViewportIdentityValid(value: unknown): boolean {
+  const viewport = cpuProfileRecord(value)
+  return (
+    typeof viewport?.width === 'number' &&
+    Number.isFinite(viewport.width) &&
+    viewport.width > 0 &&
+    typeof viewport.height === 'number' &&
+    Number.isFinite(viewport.height) &&
+    viewport.height > 0 &&
+    typeof viewport.devicePixelRatio === 'number' &&
+    Number.isFinite(viewport.devicePixelRatio) &&
+    viewport.devicePixelRatio > 0
+  )
+}
+
+export function readCpuProfileWorkloadEvidence(
+  value: unknown,
+): CpuProfileWorkloadEvidence | null {
+  const partial = cpuProfileRecord(value)
+  const browserIdentity = cpuProfileRecord(partial?.browserIdentity)
+  const browserExecutable = cpuProfileRecord(browserIdentity?.executable)
+  const runtimeIdentity = cpuProfileRecord(partial?.runtimeIdentity)
+  const engineManifest = cpuProfileRecord(runtimeIdentity?.engineManifest)
+  const hostPresentation = cpuProfileRecord(runtimeIdentity?.hostPresentation)
+  const workloadIdentity = cpuProfileRecord(partial?.workloadIdentity)
+  const stage = partial?.stage
+  const completionMarker = partial?.completionMarker
+  const expectedCaptureLabels = partial?.expectedCaptureLabels
+  const captures = partial?.captures
+  if (
+    !cpuProfileNonemptyString(stage) ||
+    !cpuProfileNonemptyString(completionMarker) ||
+    stage !== completionMarker ||
+    !Array.isArray(expectedCaptureLabels) ||
+    expectedCaptureLabels.length === 0 ||
+    expectedCaptureLabels.some(
+      (label, index, labels) =>
+        !cpuProfileNonemptyString(label) || labels.indexOf(label) !== index,
+    ) ||
+    !Array.isArray(captures) ||
+    !cpuProfileNonemptyString(browserIdentity?.name) ||
+    !cpuProfileNonemptyString(browserIdentity.version) ||
+    !cpuProfileNonemptyString(browserExecutable?.path) ||
+    !cpuProfileSha256(browserExecutable.sha256) ||
+    runtimeIdentity === null ||
+    !cpuProfileNonemptyString(engineManifest?.buildIdentity) ||
+    !cpuProfileNonemptyString(engineManifest.generation) ||
+    hostPresentation === null ||
+    !cpuProfileViewportIdentityValid(hostPresentation.rootViewport) ||
+    !cpuProfileViewportIdentityValid(hostPresentation.targetViewport) ||
+    !cpuProfileNonemptyString(workloadIdentity?.scenario) ||
+    workloadIdentity.scenario !== partial?.scenario ||
+    !cpuProfileSha256(workloadIdentity.sourceSha256)
+  ) {
+    return null
+  }
+  const captureEvidence: CpuProfileCaptureEvidence[] = []
+  for (const captureValue of captures) {
+    const capture = cpuProfileRecord(captureValue)
+    const note = cpuProfileRecord(capture?.note)
+    if (
+      !cpuProfileNonemptyString(capture?.label) ||
+      typeof note?.actionEpochMs !== 'number' ||
+      !Number.isFinite(note.actionEpochMs)
+    ) {
+      return null
+    }
+    captureEvidence.push({ label: capture.label, actionEpochMs: note.actionEpochMs })
+  }
+  if (
+    JSON.stringify(captureEvidence.map((capture) => capture.label)) !==
+    JSON.stringify(expectedCaptureLabels)
+  ) {
+    return null
+  }
+  return {
+    browserIdentity: {
+      name: browserIdentity.name,
+      version: browserIdentity.version,
+      executable: {
+        path: browserExecutable.path,
+        sha256: browserExecutable.sha256,
+      },
+    },
+    captures: captureEvidence,
+    completionMarker,
+    expectedCaptureLabels: [...expectedCaptureLabels],
+    runtimeIdentity,
+    stage,
+    workloadIdentity: {
+      scenario: workloadIdentity.scenario,
+      sourceSha256: workloadIdentity.sourceSha256,
+    },
+  }
+}
+
+export function cpuProfileInteractionBarrierValid(
+  barrier: CpuProfileInteractionBarrier | null,
+  windowStartedAtEpochMs: number,
+  windowEndedAtEpochMs: number,
+): boolean {
+  return (
+    barrier !== null &&
+    barrier.marker.length > 0 &&
+    barrier.releasedBy === 'profiler' &&
+    Number.isFinite(barrier.reachedAtEpochMs) &&
+    Number.isFinite(barrier.releasedAtEpochMs) &&
+    barrier.reachedAtEpochMs <= barrier.releasedAtEpochMs &&
+    barrier.releasedAtEpochMs >= windowStartedAtEpochMs &&
+    barrier.releasedAtEpochMs <= windowEndedAtEpochMs
+  )
+}
+
+function readInteractionBarrierState(
+  value: unknown,
+): CpuProfileInteractionBarrier | null {
+  if (!value || typeof value !== 'object') return null
+  const marker = Reflect.get(value, 'marker')
+  const reachedAtEpochMs = Reflect.get(value, 'reachedAtEpochMs')
+  const releasedBy = Reflect.get(value, 'releasedBy')
+  const releasedAtEpochMs = Reflect.get(value, 'releasedAtEpochMs')
+  if (
+    typeof marker !== 'string' ||
+    typeof reachedAtEpochMs !== 'number' ||
+    typeof releasedBy !== 'string' ||
+    typeof releasedAtEpochMs !== 'number'
+  ) {
+    return null
+  }
+  return { marker, reachedAtEpochMs, releasedBy, releasedAtEpochMs }
+}
+
+export async function runCpuProfile(
+  args: string[],
+  opts: ProfileOptions,
+): Promise<number> {
+  const duration = Number(valueOf(args, '--duration') ?? '5')
+  if (!Number.isFinite(duration) || duration <= 0) {
+    console.error('  --duration must be a positive number (seconds)')
+    return 1
+  }
+  const sampleInterval = Number(valueOf(args, '--sample-interval') ?? '0.1') // ms
+  const interactionBarrierEnabled = args.includes('--interaction-barrier')
+  const interactionBarrierTimeoutSeconds = Number(
+    valueOf(args, '--interaction-barrier-timeout') ?? '90',
+  )
+  if (
+    !Number.isFinite(interactionBarrierTimeoutSeconds) ||
+    interactionBarrierTimeoutSeconds <= 0
+  ) {
+    console.error('  --interaction-barrier-timeout must be positive (seconds)')
+    return 1
+  }
+  const interactionBarrierLeaseMs = Math.min(
+    2_147_000_000,
+    Math.ceil((interactionBarrierTimeoutSeconds + duration + 5) * 1000),
+  )
+  const cdpPort = Number(
+    valueOf(args, '--cdp-port') ?? process.env.RNX_CDP_PORT ?? '9222',
+  )
+  // optional substring filter to pick the right page when several sims share
+  // the CDP browser (e.g. `--match 8089` or `--match /rn/8089`).
+  const match = valueOf(args, '--match') ?? '/rn/'
+  const outputArg = valueOf(args, '--output') ?? valueOf(args, '-o')
+  const outputPath = resolve(process.cwd(), outputArg ?? '/tmp/rnx.cpuprofile')
+
+  // locate the page target on the CDP endpoint. NOTE: Chrome's DevTools HTTP
+  // `/json` endpoints reject any Host header that isn't `localhost` (a
+  // DNS-rebinding guard) — `http://127.0.0.1:<port>/json/list` returns
+  // "Not found" / 404, so we must use the `localhost` hostname here. (this is
+  // what made the command silently fall into the no-CDP path even with a live
+  // CDP browser.)
+  let targets: CdpTarget[] = []
+  try {
+    targets = (await (
+      await fetch(`http://localhost:${cdpPort}/json/list`)
+    ).json()) as CdpTarget[]
+  } catch {
+    printNoCdp(cdpPort)
+    return 1
+  }
+  const page = targets.find((t) => t.type === 'page' && t.url.includes(match))
+  if (!page) {
+    console.error(`  no page target matching "${match}" on CDP :${cdpPort}`)
+    console.error(`  open targets: ${targets.map((t) => t.url).join(', ') || '(none)'}`)
+    return 1
+  }
+
+  const cdp = new Cdp(page.webSocketDebuggerUrl)
+  await cdp.waitOpen()
+  let interactionBarrierInstalled = false
+  const evaluatePage = async (expression: string): Promise<unknown> => {
+    const response = await cdp.send('Runtime.evaluate', {
+      expression,
+      returnByValue: true,
+    })
+    if (response?.exceptionDetails) {
+      throw new Error(
+        `page evaluation failed: ${response.exceptionDetails.text ?? 'unknown error'}`,
+      )
+    }
+    return response?.result?.value
+  }
+  const releaseInteractionBarrier = (releasedBy: 'cleanup' | 'profiler') =>
+    evaluatePage(`(() => {
+      const release = Reflect.get(globalThis, '__sootsimReleaseCpuProfileBarrier')
+      return typeof release === 'function'
+        ? Reflect.apply(release, globalThis, [${JSON.stringify(releasedBy)}])
+        : null
+    })()`)
+  try {
+    if (interactionBarrierEnabled) {
+      const installed = await evaluatePage(`(() => {
+        const state = {
+          marker: null,
+          reachedAtEpochMs: null,
+          releasedBy: null,
+          releasedAtEpochMs: null,
+        }
+        let releaseGate = () => {}
+        const gate = new Promise((resolve) => {
+          releaseGate = resolve
+        })
+        Reflect.set(globalThis, '__sootsimCpuProfileBarrierState', state)
+        Reflect.set(globalThis, '__sootsimCpuProfileBarrier', async (marker) => {
+          if (state.marker === null) {
+            state.marker = String(marker)
+            state.reachedAtEpochMs = Date.now()
+          }
+          await gate
+        })
+        let lease = null
+        const releaseBarrier = (releasedBy) => {
+          if (state.releasedAtEpochMs === null) {
+            state.releasedAtEpochMs = Date.now()
+            state.releasedBy = String(releasedBy)
+            if (lease !== null) clearTimeout(lease)
+            releaseGate()
+          }
+          return { ...state }
+        }
+        lease = setTimeout(
+          () => releaseBarrier('lease'),
+          ${interactionBarrierLeaseMs},
+        )
+        Reflect.set(globalThis, '__sootsimReleaseCpuProfileBarrier', releaseBarrier)
+        return true
+      })()`)
+      if (installed !== true) {
+        console.error('  failed to install the interaction profile barrier')
+        return 1
+      }
+      interactionBarrierInstalled = true
+    }
+
+    // discover every child worker. keep detached entries in the manifest: a
+    // worker can exit during the capture, and deleting it used to make the
+    // command either mislabel the busiest survivor as "tenant" or lose the
+    // entire run when Profiler.stop hit the detached session first.
+    const workers = new Map<string, AttachedTarget>()
+    let captureStarted = false
+    let captureWindowClosed = false
+    const startPromises: Array<Promise<void>> = []
+    const discoveryPromises: Array<Promise<void>> = []
+    let attachmentGeneration = 0
+    let awaitedDiscoveryCount = 0
+    let awaitedStartCount = 0
+    const enableRecursiveAutoAttach = (sessionId?: string) =>
+      cdp.send(
+        'Target.setAutoAttach',
+        {
+          autoAttach: true,
+          waitForDebuggerOnStart: false,
+          flatten: true,
+        },
+        sessionId,
+      )
+    const startTarget = async (target: AttachedTarget) => {
+      try {
+        await cdp.send('Profiler.enable', {}, target.sessionId)
+        await cdp.send(
+          'Profiler.setSamplingInterval',
+          { interval: sampleInterval * 1000 },
+          target.sessionId,
+        )
+        await cdp.send('Profiler.start', {}, target.sessionId)
+        target.started = true
+        target.profileStartedAtMs = performance.now()
+      } catch (error) {
+        target.error = error instanceof Error ? error.message : String(error)
+      }
+    }
+    const waitForStableTargetSetup = async () => {
+      while (true) {
+        const observedGeneration = attachmentGeneration
+        if (awaitedDiscoveryCount < discoveryPromises.length) {
+          const pendingDiscoveries = discoveryPromises.slice(awaitedDiscoveryCount)
+          awaitedDiscoveryCount = discoveryPromises.length
+          await Promise.all(pendingDiscoveries)
+        }
+        if (awaitedStartCount < startPromises.length) {
+          const pendingStarts = startPromises.slice(awaitedStartCount)
+          awaitedStartCount = startPromises.length
+          await Promise.all(pendingStarts)
+        }
+        // recursive auto-attach notifications can arrive just after the CDP
+        // command resolves. require a quiet generation before releasing work.
+        await sleep(50)
+        if (
+          observedGeneration === attachmentGeneration &&
+          awaitedDiscoveryCount === discoveryPromises.length &&
+          awaitedStartCount === startPromises.length
+        ) {
+          return
+        }
+      }
+    }
+    cdp.on((method, params) => {
+      if (method === 'Target.attachedToTarget' && params.targetInfo?.type === 'worker') {
+        if (captureWindowClosed) return
+        const sessionId = params.sessionId
+        const targetInfo = params.targetInfo
+        const target: AttachedTarget = {
+          attachedAtMs: performance.now(),
+          detached: false,
+          role: cpuProfileTargetRole(targetInfo.url, targetInfo.title),
+          sessionId,
+          started: false,
+          title: targetInfo.title ?? '',
+          type: targetInfo.type,
+          url: targetInfo.url,
+        }
+        workers.set(sessionId, target)
+        attachmentGeneration += 1
+        discoveryPromises.push(
+          enableRecursiveAutoAttach(sessionId).catch((error: unknown) => {
+            target.error = `recursive auto-attach failed: ${error instanceof Error ? error.message : String(error)}`
+          }),
+        )
+        if (captureStarted) startPromises.push(startTarget(target))
+      }
+      if (method === 'Target.detachedFromTarget') {
+        const target = workers.get(params.sessionId)
+        if (target) {
+          target.detached = true
+          target.detachedAtMs = performance.now()
+        }
+      }
+    })
+    await enableRecursiveAutoAttach()
+    // auto-attach events arrive asynchronously after the call resolves.
+    await sleep(500)
+    await waitForStableTargetSetup()
+    const pageTarget: AttachedTarget = {
+      attachedAtMs: performance.now(),
+      detached: false,
+      role: 'page',
+      started: false,
+      title: page.title ?? '',
+      type: 'page',
+      url: page.url,
+    }
+    if (interactionBarrierEnabled) {
+      console.log('  waiting for the workload interaction barrier…')
+      const deadline = performance.now() + interactionBarrierTimeoutSeconds * 1000
+      let reached = false
+      while (performance.now() < deadline) {
+        const value = await evaluatePage(`(() => {
+          const state = Reflect.get(globalThis, '__sootsimCpuProfileBarrierState')
+          if (!state || typeof state !== 'object') return null
+          return {
+            marker: Reflect.get(state, 'marker'),
+            reachedAtEpochMs: Reflect.get(state, 'reachedAtEpochMs'),
+          }
+        })()`)
+        if (
+          value &&
+          typeof value === 'object' &&
+          typeof Reflect.get(value, 'marker') === 'string' &&
+          typeof Reflect.get(value, 'reachedAtEpochMs') === 'number'
+        ) {
+          reached = true
+          break
+        }
+        await sleep(25)
+      }
+      if (!reached) {
+        console.error(
+          `  workload interaction barrier was not reached within ${interactionBarrierTimeoutSeconds}s`,
+        )
+        return 1
+      }
+    }
+    captureStarted = true
+    startPromises.push(startTarget(pageTarget))
+    for (const target of workers.values()) startPromises.push(startTarget(target))
+    await waitForStableTargetSetup()
+    const startedCount = [pageTarget, ...workers.values()].filter(
+      (target) => target.started,
+    ).length
+    if (startedCount === 0) {
+      console.error('  no CDP targets accepted Profiler.start')
+      return 1
+    }
+    const captureWindowStartedAtMs = performance.now()
+    const captureWindowStartedAtEpochMs = Date.now()
+    const captureWindowEndedAtMs = captureWindowStartedAtMs + duration * 1000
+    const captureWindowEndedAtEpochMs = captureWindowStartedAtEpochMs + duration * 1000
+    const interactionBarrier = interactionBarrierEnabled
+      ? readInteractionBarrierState(await releaseInteractionBarrier('profiler'))
+      : null
+    if (opts.verbose) {
+      for (const target of [pageTarget, ...workers.values()]) {
+        console.log(
+          `  target ${target.role} ${target.type} ${target.title || '(untitled)'} ${target.url}`,
+        )
+      }
+    }
+    console.log(
+      `  recording ${duration}s across ${startedCount} target(s) — interact now…`,
+    )
+    await sleep(Math.max(0, captureWindowEndedAtMs - performance.now()))
+    captureStarted = false
+    captureWindowClosed = true
+    await Promise.allSettled(startPromises)
+    const results = [pageTarget, ...workers.values()]
+    await Promise.all(
+      results.map(async (target) => {
+        if (!target.started) return
+        try {
+          const { profile } = await cdp.send('Profiler.stop', {}, target.sessionId)
+          target.profile = profile
+          target.profileStoppedAtMs = performance.now()
+        } catch (error) {
+          target.error = error instanceof Error ? error.message : String(error)
+          target.profileStoppedAtMs = target.detachedAtMs
+        }
+        await cdp.send('Profiler.disable', {}, target.sessionId).catch(() => {})
+      }),
+    )
+    // querying the page while five high-frequency profilers are still active
+    // can itself time out and lengthen the requested sampling interval. stop
+    // first, then read the already-recorded workload completion evidence.
+    const workloadEvidence = interactionBarrierEnabled
+      ? readCpuProfileWorkloadEvidence(
+          await evaluatePage(
+            `Reflect.get(globalThis, '__sootsimInteractionPartialResult') ?? null`,
+          ),
+        )
+      : null
+    const workloadActionEpochMs =
+      workloadEvidence?.captures.map((capture) => capture.actionEpochMs) ?? []
+
+    mkdirSync(dirname(outputPath), { recursive: true })
+    const roleLabels = cpuProfileRoleLabels(
+      results.map((target) => ({
+        captured: target.profile !== undefined,
+        role: target.role,
+      })),
+    )
+    const manifest = results.map((target, index) => {
+      const coverage = cpuProfileCoverage(
+        target.profileStartedAtMs,
+        target.profileStoppedAtMs,
+        captureWindowStartedAtMs,
+        captureWindowEndedAtMs,
+      )
+      const role = roleLabels[index]
+      const profilePath = target.profile
+        ? outputPath.replace(/(\.[^.]+)?$/, `.${role}$1`)
+        : null
+      if (profilePath) {
+        writeFileSync(profilePath, JSON.stringify(target.profile))
+        console.log(
+          `  ${role} ${shortUrl(target.url)}: ${target.profile.samples.length} samples → ${profilePath}`,
+        )
+      } else {
+        console.error(
+          `  ${role} ${shortUrl(target.url)}: no profile${target.error ? ` — ${target.error}` : ''}`,
+        )
+      }
+      if (opts.verbose && target.profile?.samples.length > 0) {
+        for (const fn of topSelfTime(target.profile, 12)) {
+          console.log(`      ${fn.pct.toFixed(1).padStart(5)}%  ${fn.name}  ${fn.url}`)
+        }
+      }
+      return {
+        role,
+        baseRole: target.role,
+        type: target.type,
+        title: target.title,
+        url: target.url,
+        detached: target.detached,
+        attachedOffsetMs: target.attachedAtMs - captureWindowStartedAtMs,
+        detachedOffsetMs:
+          target.detachedAtMs === undefined
+            ? null
+            : target.detachedAtMs - captureWindowStartedAtMs,
+        requiredForComplete: cpuProfileTargetOverlapsWindow(
+          target.detachedAtMs,
+          captureWindowStartedAtMs,
+        ),
+        ...coverage,
+        samples: target.profile?.samples.length ?? 0,
+        profilePath,
+        error: target.error ?? null,
+      }
+    })
+    const requiredRoles = ['page', 'shell', 'compositor', 'tenant']
+    const capturedRoles = new Set(
+      manifest
+        .filter((target) => target.requiredForComplete && target.profilePath !== null)
+        .map((target) => target.baseRole),
+    )
+    const missingRoles = requiredRoles.filter((role) => !capturedRoles.has(role))
+    const interactionBarrierComplete =
+      !interactionBarrierEnabled ||
+      (cpuProfileInteractionBarrierValid(
+        interactionBarrier,
+        captureWindowStartedAtEpochMs,
+        captureWindowEndedAtEpochMs,
+      ) &&
+        workloadEvidence !== null &&
+        cpuProfileActionsWithinWindow(
+          workloadActionEpochMs,
+          captureWindowStartedAtEpochMs,
+          captureWindowEndedAtEpochMs,
+        ))
+    const complete =
+      missingRoles.length === 0 &&
+      interactionBarrierComplete &&
+      manifest.length > 0 &&
+      manifest
+        .filter((target) => target.requiredForComplete)
+        .every(
+          (target) =>
+            target.profilePath !== null &&
+            target.error === null &&
+            target.coverageRatio >= 0.99,
+        )
+    const manifestPath = outputPath.replace(/(\.[^.]+)?$/, '.manifest.json')
+    const executableSha256 = IS_STANDALONE
+      ? createHash('sha256').update(readFileSync(process.execPath)).digest('hex')
+      : null
+    writeFileSync(
+      manifestPath,
+      JSON.stringify(
+        {
+          cli: {
+            version: getCliVersion(),
+            standalone: IS_STANDALONE,
+            executablePath: process.execPath,
+            executableSha256,
+            argv: process.argv.slice(1),
+          },
+          page: page.url,
+          complete,
+          missingRoles,
+          requestedDurationMs: duration * 1000,
+          captureWindowStartedAt: new Date(captureWindowStartedAtEpochMs).toISOString(),
+          captureWindowEndedAt: new Date(captureWindowEndedAtEpochMs).toISOString(),
+          interactionBarrier,
+          workloadEvidence,
+          workloadActionEpochMs,
+          manifest,
+        },
+        null,
+        2,
+      ),
+    )
+    console.log(`  manifest → ${manifestPath}`)
+    if (!complete) {
+      console.error(
+        `  incomplete attribution capture${missingRoles.length ? ` — missing ${missingRoles.join(', ')}` : ''}`,
+      )
+      if (!interactionBarrierComplete) {
+        console.error(
+          '  workload did not complete every expected action inside the interaction profile window',
+        )
+      }
+    }
+    console.log('  open in chrome devtools → Performance → Load profile to inspect.')
+    return complete ? 0 : 1
+  } finally {
+    if (interactionBarrierInstalled) {
+      await releaseInteractionBarrier('cleanup').catch(() => {})
+    }
+    cdp.close()
+  }
+}
+
+function printNoCdp(cdpPort: number) {
+  console.error(`  perf cpu needs a CDP-enabled browser on :${cdpPort}.`)
+  console.error(
+    "  the tenant worker can't be profiled via the JS Self-Profiler API (F28),",
+  )
+  console.error('  so the sim must expose Chrome remote debugging. easiest path —')
+  console.error('  open the sim with a CDP port (it stays driveable over the bridge,')
+  console.error('  so you can scroll/navigate while profiling):')
+  console.error('')
+  console.error(
+    `    rnx open <metro-port> --new --driver playwright --cdp-port ${cdpPort}`,
+  )
+  console.error(`    rnx perf cpu --cdp-port ${cdpPort} --match <metro-port>`)
+  console.error('')
+  console.error('  or launch a standalone CDP Chrome (not bridge-driveable):')
+  console.error('')
+  console.error('    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \\')
+  console.error(
+    `      --remote-debugging-port=${cdpPort} --user-data-dir=/tmp/rnx-cdp \\`,
+  )
+  console.error('      --no-sandbox --disable-gpu-sandbox \\')
+  // never suggest swiftshader — software rendering pegs every core for the
+  // browser's lifetime (documented machine-freeze cause). metal is the real
+  // rendering path anyway, so the profile is representative.
+  console.error('      --use-gl=angle --use-angle=metal \\')
+  console.error('      "http://localhost:5173/rn/<metro-port>" &')
+  console.error('')
+  console.error('  override the port with --cdp-port or $RNX_CDP_PORT.')
+}
+
+function shortUrl(url: string): string {
+  if (!url) return '(native)'
+  return url
+    .replace(/^https?:\/\/[^/]+/, '')
+    .replace(/\?.*$/, '')
+    .slice(-50)
+}
+
+export function cpuProfileTargetRole(url: string, title = ''): string {
+  const identity = `${title} ${url}`.toLowerCase()
+  if (identity.includes('compositor-worker') || identity.includes('sootsim-compositor')) {
+    return 'compositor'
+  }
+  if (identity.includes('shell-worker')) return 'shell'
+  if (identity.includes('named-worklet')) return 'worklet'
+  if (identity.includes('render-worker') || identity.includes('tenant-worker')) {
+    return 'tenant'
+  }
+  return 'worker'
+}
+
+function topSelfTime(profile: any, topN: number) {
+  const total = profile.samples.length || 1
+  const byFn = new Map<string, { self: number; name: string; url: string }>()
+  for (const node of profile.nodes) {
+    const f = node.callFrame
+    const key = `${f.functionName || '(anonymous)'}@${shortUrl(f.url)}:${f.lineNumber}`
+    const cur = byFn.get(key) ?? {
+      self: 0,
+      name: f.functionName || '(anonymous)',
+      url: `${shortUrl(f.url)}:${f.lineNumber}`,
+    }
+    cur.self += node.hitCount ?? 0
+    byFn.set(key, cur)
+  }
+  return [...byFn.values()]
+    .map((v) => ({ ...v, pct: (v.self / total) * 100 }))
+    .sort((a, b) => b.self - a.self)
+    .slice(0, topN)
+}
+
+function valueOf(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag)
+  if (i < 0 || i === args.length - 1) return undefined
+  return args[i + 1]
+}