peachsim 0.1.1625 → 0.1.1635

package/cli/commands/upload.ts

@@ -9,7 +9,8 @@
 // associated with the user's account.
 
 import { createHash, randomUUID } from 'crypto'
-import { readFileSync } from 'fs'
+import { readFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
 import path from 'path'
 import { gzipSync, gunzipSync } from 'zlib'
 import { readProfileTrace } from '@peach/globals/profile-trace'
@@ -36,11 +37,13 @@ import {
   mergeProfileTimeline,
   profileFrameSummary,
 } from 'peach-engine/profiler/profile-trace'
+import { readSceneRecordingUpload } from 'peach-engine/remote-stream/scene-recording'
 import {
   resolvedExpoAppIconUrl,
   expoConfigFromManifest,
 } from '../../../peach-engine/src/engine/expo-manifest'
 import { loopbackOriginOf } from '../../src/backend-origin'
+import { parseExpoManifestBody } from '../../src/expo-manifest-body'
 import { rnxPublicBrand } from '../../src/public-brand'
 import { fetchAppFontFiles } from '../app-fonts'
 import { fetchAppSplashImages } from '../app-splash'
@@ -194,8 +197,8 @@ options:
                      for prod uploads, upload origin for localhost/custom origins).
                      override with PEACH_PREVIEW_ORIGIN env var
   --events <path>    path to a gzipped events .jsonl.gz file to attach
-                     required unless --video is present; previews must
-                     have replay or recording playback data
+                     required unless --video or --scene is present;
+                     previews must have replay or recording playback data
   --screenshot <path>
                      path to a PNG thumbnail to attach to the share
   --snapshot-manifest <path>
@@ -205,6 +208,9 @@ options:
                      /api/preview/flow-video?id=<share-id>
   --video-duration-ms <ms>
                      duration hint for attached flow video
+  --scene <path>     a scene recording (.psr.gz) of a remote viewer's display
+                     stream. the preview paints it through the simulator's
+                     renderer instead of playing a video
   --timeline-events <path>
                      extra trace timeline rows, JSONL or JSONL gz
   --trace-profile <path>
@@ -436,6 +442,7 @@ export async function runUpload(
   const screenshotPath = extractStringFlag(mutableArgs, '--screenshot')
   const snapshotManifestPath = extractStringFlag(mutableArgs, '--snapshot-manifest')
   const videoPath = extractStringFlag(mutableArgs, '--video')
+  const scenePath = extractStringFlag(mutableArgs, '--scene')
   const timelineEventsPath = extractStringFlag(mutableArgs, '--timeline-events')
   const traceProfilePath = extractStringFlag(mutableArgs, '--trace-profile')
   const failureBundleDir = extractStringFlag(mutableArgs, '--failure-bundle')
@@ -468,9 +475,9 @@ export async function runUpload(
     console.error('  --billing-kind test_run is only for hosted test jobs')
     peachExit(1)
   }
-  if (!eventsPath && !videoPath) {
+  if (!eventsPath && !videoPath && !scenePath) {
     console.error(
-      '  preview uploads require playback data: pass --events or --video.\n' +
+      '  preview uploads require playback data: pass --events, --video or --scene.\n' +
         '  for a normal local preview, use `peach record --mode combined --open`\n' +
         '  or `peach maestro test --preview` instead of uploading a bundle-only snapshot.',
     )
@@ -493,6 +500,7 @@ export async function runUpload(
   })
 
   const bridge = createBridgeFromParsed(parsed)
+  let shellUrl: string | null = null
   let snapshot: BundleSnapshot
   // bundle-origin manifest (no bodies) — CLI re-fetches these over http so
   // they can be large without blowing the ws frame cap. sibling bundle
@@ -513,6 +521,7 @@ export async function runUpload(
   const localTraceTimelineCount = traceTimelineEvents.length
   let transformedBundleText: string | null = null
   try {
+    if (scenePath) shellUrl = await evalInBridge<string>(bridge, 'location.href')
     snapshot = await evalInBridge<BundleSnapshot>(
       bridge,
       '(typeof window.__sootsimCaptureBundle === "function") ? window.__sootsimCaptureBundle() : null',
@@ -872,6 +881,17 @@ export async function runUpload(
     )
   }
 
+  let sceneBytes: Uint8Array | undefined
+  let sceneStream: InitRequestBody['sceneStream']
+  if (scenePath) {
+    sceneBytes = readFileSync(scenePath)
+    const { header, slot } = await readSceneRecordingUpload(sceneBytes)
+    sceneStream = slot
+    console.log(
+      `  attaching scene stream: ${(sceneBytes.byteLength / 1024).toFixed(1)} KiB, ${header.frameCount} frames over ${Math.round(header.durationMs)}ms`,
+    )
+  }
+
   // priority: PEACH_API_KEY env → github runner token → saved credential
   // file → session token. github runner auth is what keeps installed PR
   // previews from requiring a new Contrast secret.
@@ -883,6 +903,21 @@ export async function runUpload(
     console.error('  set PEACH_API_KEY=sk_rnx_... or run `peach login`.')
     peachExit(1)
   }
+  if (sceneBytes && shellUrl && cliAuth.kind === 'github') {
+    const { renderSceneToVideo } = await import('../scene-video')
+    const output = path.join(tmpdir(), `peach-scene-video-${Date.now()}.mp4`)
+    try {
+      const rendered = await renderSceneToVideo({ scene: sceneBytes, shellUrl, output })
+      videoBytes = readFileSync(output)
+      videoContentType = 'video/mp4'
+      videoDurationMs = rendered.durationMs
+      console.log(
+        `  rendered scene video: ${rendered.frameCount} frames at 60 fps, ${rendered.sizeBytes} bytes in ${(rendered.renderTimeMs / 1000).toFixed(1)}s`,
+      )
+    } finally {
+      rmSync(output, { force: true })
+    }
+  }
   const resolvedAuthHeader = authHeaderValue(cliAuth)
 
   const bundleOrigin = (() => {
@@ -1010,8 +1045,8 @@ export async function runUpload(
       headers: { 'expo-platform': platform, accept: 'application/json' },
       signal: AbortSignal.timeout(30_000),
     })
-    if (response.ok && response.headers.get('content-type')?.includes('json')) {
-      const manifest: unknown = await response.json()
+    if (response.ok && !response.headers.get('content-type')?.includes('html')) {
+      const manifest: unknown = parseExpoManifestBody(await response.text())
       const config = expoConfigFromManifest(manifest)
       if (config) {
         appManifest = manifestUrl
@@ -1179,6 +1214,7 @@ export async function runUpload(
             durationMs: videoDurationMs,
           }
         : undefined,
+    sceneStream,
   }
 
   const filesByHash = new Map<string, Uint8Array>()
@@ -1201,6 +1237,7 @@ export async function runUpload(
   for (const snapshot of interactionSnapshots) putBytes += snapshot.bytes.byteLength
   if (failureBundleGz) putBytes += failureBundleGz.byteLength
   if (videoBytes) putBytes += videoBytes.byteLength
+  if (sceneBytes) putBytes += sceneBytes.byteLength
 
   const initUrl = `${normalizeOrigin(origin)}/api/preview/upload/init`
   console.log(`  init: ${initUrl}`)
@@ -1217,6 +1254,7 @@ export async function runUpload(
         timelineBytes: timelineGz,
         storageBytes: storageGz,
         videoBytes,
+        sceneStreamBytes: sceneBytes,
         failureBundleBytes: failureBundleGz,
         snapshotBytes,
       },
@@ -1232,6 +1270,7 @@ export async function runUpload(
       (result.init.storage ? 1 : 0) +
       result.init.snapshots.length +
       (result.init.flowVideo ? 1 : 0) +
+      (result.init.sceneStream ? 1 : 0) +
       (result.init.failureBundle ? 1 : 0)
     console.log(
       `  PUT ${totalObjects} objects in ${Date.now() - putT0}ms (${(putBytes / 1024).toFixed(1)} KiB)`,

package/cli/desktop-companion.ts

@@ -1,9 +1,29 @@
 import { execFileSync, spawn } from 'child_process'
-import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs'
+import { createHash } from 'node:crypto'
+import { tmpdir } from 'os'
 import { dirname, join, resolve } from 'path'
 import { fileURLToPath } from 'url'
-import { activeDesktopHostApp, isNativeHostBundle } from '../src/desktop-host-delivery'
-import { rnxHomeDir } from '../src/home-paths'
+import {
+  activeDesktopHostApp,
+  desktopHostPlatform,
+  isNativeHostBundle,
+} from '../src/desktop-host-delivery'
+import {
+  isDaemonLockfileFresh,
+  isDevBridgeLockfileFresh,
+  readDaemonLockfile,
+  readDevBridgeLockfiles,
+  rnxHomeDir,
+} from '../src/home-paths'
 
 // resolved lazily: peach-engine is a workspace package in dev, but absent
 // from the published npm tarball. don't crash module load just because the
@@ -95,22 +115,31 @@ export function findInstalledDesktopCompanion(): DesktopCompanionInstall | null
     : findNativeDesktopCompanion()
 }
 
+// leftover Electron bundles. /Applications/Peach.app is the native host on a
+// case-insensitive volume, so bundle id decides, not the path's letter case.
+function retiredElectronApps(): string[] {
+  if (process.platform === 'darwin') {
+    return [
+      '/Applications/peach.app',
+      resolve(process.env.HOME || '', 'Applications/peach.app'),
+    ].filter((candidate) => existsSync(candidate) && !isNativeHostBundle(candidate))
+  }
+  if (process.platform !== 'linux') return []
+  return [
+    resolve(process.env.HOME || '', 'Applications/peach.AppImage'),
+    resolve(process.env.HOME || '', '.local/bin/peach.AppImage'),
+    '/opt/peach/peach.AppImage',
+    '/opt/peach/peach',
+  ].filter((candidate) => existsSync(candidate))
+}
+
 // existing Electron apps stay on disk; CLI users receive the migration once.
+// the notice names those apps and does not reject a native host beside them.
 export function notifyDesktopMigration(): void {
   if (process.platform !== 'darwin' && process.platform !== 'linux') return
-  const legacy =
-    process.platform === 'darwin'
-      ? [
-          '/Applications/peach.app',
-          resolve(process.env.HOME || '', 'Applications/peach.app'),
-        ].some((candidate) => existsSync(candidate) && !isNativeHostBundle(candidate))
-      : ['Applications/peach.AppImage', '.local/bin/peach.AppImage'].some((candidate) =>
-          existsSync(resolve(process.env.HOME || '', candidate)),
-        ) ||
-        existsSync('/opt/peach/peach.AppImage') ||
-        existsSync('/opt/peach/peach')
+  const legacy = retiredElectronApps()
   const marker = join(rnxHomeDir(), 'electron-native-migration')
-  if (!legacy || existsSync(marker)) return
+  if (legacy.length === 0 || existsSync(marker)) return
   mkdirSync(rnxHomeDir(), { recursive: true })
   try {
     writeFileSync(marker, '', { flag: 'wx' })
@@ -119,7 +148,7 @@ export function notifyDesktopMigration(): void {
     throw error
   }
   console.error(
-    '  Electron has retired on Mac and Linux. Install the native app: peach desktop install',
+    `  Electron has retired on Mac and Linux (${legacy.join(', ')}). Install the native app: peach desktop install`,
   )
 }
 
@@ -154,6 +183,21 @@ export function wantsNativeDesktop(opts: DesktopCompanionOptions = {}): boolean
   )
 }
 
+// the native app is the simulator window wherever it ships: always on Apple
+// silicon, and on Linux x64 in a desktop session once installed or when a
+// person is present to approve its package install's sudo prompt.
+export function nativeDesktopIsDefault(): boolean {
+  const platform = desktopHostPlatform()
+  if (platform === 'mac-arm64') return true
+  if (platform !== 'linux-x64') return false
+  if (!process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return false
+  return (
+    findNativeDesktopCompanion() !== null ||
+    process.stdin.isTTY === true ||
+    process.getuid?.() === 0
+  )
+}
+
 export function getNativeDesktopAppPath(): string | null {
   const explicitApp = process.env.PEACH_DESKTOP_APP
   if (!explicitApp)
@@ -284,6 +328,47 @@ async function openInConnectedMacApp(
   }
 }
 
+// PeachDesktop shipped before PEACH_BRIDGE_PORT seeds the page from
+// PEACH_HOME/daemon.json and ignores the launch URL's wsPort. when this
+// command is waiting on a different bridge, give the child a home whose
+// lock names that bridge. the caller's daemon.json is left untouched.
+// a newer host that prefers the env, the URL pin, or a fresh daemon still
+// sees this same port (the isolated-home rule in desktop host bridge selection).
+function macDesktopLaunchHome(bridgePort: number): string {
+  const home = rnxHomeDir()
+  const daemon = readDaemonLockfile()
+  if (isDaemonLockfileFresh(daemon) && daemon.bridgePort === bridgePort) return home
+  const dev = readDevBridgeLockfiles().find(
+    (lock) => lock.bridgePort === bridgePort && isDevBridgeLockfileFresh(lock),
+  )
+  const homeKey = createHash('sha256').update(home).digest('hex')
+  const dir = join(tmpdir(), 'peach-desktop-launch', homeKey, String(bridgePort))
+  mkdirSync(dir, { recursive: true })
+  if (existsSync(home)) {
+    for (const name of readdirSync(home)) {
+      if (name === 'daemon.json') continue
+      const dest = join(dir, name)
+      try {
+        lstatSync(dest)
+      } catch {
+        symlinkSync(join(home, name), dest)
+      }
+    }
+  }
+  const lockPath = join(dir, 'daemon.json')
+  try {
+    if (lstatSync(lockPath).isSymbolicLink()) unlinkSync(lockPath)
+  } catch {
+    // no lock yet
+  }
+  const pid = dev && dev.pid > 1 ? dev.pid : process.pid
+  writeFileSync(
+    lockPath,
+    JSON.stringify({ schema: 1, pid, bridgePort, heartbeatAt: Date.now() }),
+  )
+  return dir
+}
+
 export async function launchDesktopCompanion(
   url?: string,
   install = findDesktopCompanion(),
@@ -339,7 +424,7 @@ export async function launchDesktopCompanion(
       '-a',
       install.path,
       '--env',
-      `PEACH_HOME=${rnxHomeDir()}`,
+      `PEACH_HOME=${opts.bridgePort && launchUrl ? macDesktopLaunchHome(opts.bridgePort) : rnxHomeDir()}`,
     ]
     if (opts.bridgePort) {
       openArgs.push('--env', `PEACH_BRIDGE_PORT=${opts.bridgePort}`)

package/cli/drivers/desktop.ts

@@ -1,5 +1,6 @@
 // desktop driver selection is shared with companion discovery.
 
+import { desktopHostPlatform, headlessHostCommand } from '../../src/desktop-host-delivery'
 import {
   findDesktopCompanion,
   launchDesktopCompanion,
@@ -18,7 +19,19 @@ export function createDesktopDriver(id: 'desktop' | 'electron'): Driver {
   const missing = `peach ${id} app not installed (run \`peach desktop install${native ? '' : ' --electron'}\`)`
   function probe(): DriverAvailability {
     const install = findDesktopCompanion({ native })
-    if (!install) return { available: false, reason: missing }
+    if (!install) {
+      const host =
+        id === 'desktop' && native && desktopHostPlatform() === 'linux-x64'
+          ? headlessHostCommand()
+          : null
+      return host
+        ? {
+            available: true,
+            reason: null,
+            detail: `headless host @ ${host[0]} (use --driver playwright --headless)`,
+          }
+        : { available: false, reason: missing }
+    }
     return {
       available: true,
       reason: null,

package/cli/drivers/playwright-sim-host.ts

@@ -18,6 +18,7 @@ import {
 // require, in a child process the CLI spawns as itself.
 import {
   chromeDisabledFeaturesSwitch,
+  LINUX_CHROME_SCOPE_ENV,
   softwareChromeLaunchOptions,
 } from '../../../../scripts/lib/reap-browser'
 import { createBrowserPageTargetReader } from '../../../peach-engine/src/browser-page-target'
@@ -27,6 +28,7 @@ import {
 } from '../../../peach-engine/src/capture/browser-composite'
 import { WEBVIEW_HOST_BOOTSTRAP_SOURCE } from '../../../peach-engine/src/components/native-ui/webview-frame-bridge'
 import { createBrowserPointerDispatcher } from '../../../peach-engine/src/render-worker/browser-pointer'
+import { automateWebAuthenticationSessions } from '../../../peach-engine/src/web-authentication-automation-host'
 import {
   automateWebViewFrames,
   WEBVIEW_HOST_BINDING,
@@ -69,6 +71,9 @@ const callerUserDataDir = process.env.SOOTSIM_PW_USERDATADIR || '';
 // SOOTSIM_PW_OWNER_POLL_MS is a test-only override of the 5s poll interval;
 // production never sets it.
 const ownerPid = Number(process.env.SOOTSIM_PW_OWNER_PID || 0);
+// the open command waiting for this host to connect; it may queue for the
+// browser slot and then be killed by its own caller's budget.
+const launcherPid = Number(process.env.SOOTSIM_PW_LAUNCHER_PID || 0);
 const ownerPollMs = Number(process.env.SOOTSIM_PW_OWNER_POLL_MS || 5000);
 // optional CDP port — exposes Chrome's remote-debugging endpoint so a
 // bridge-driven sim can also be cpu-profiled (peach perf cpu --cdp-port).
@@ -110,6 +115,7 @@ const viewport = viewportSpec
 const deviceScaleFactor = Number(process.env.SOOTSIM_PW_DSF || 2);
 const closeTimeoutMs = Number(process.env.SOOTSIM_PW_CLOSE_TIMEOUT_MS || 2500);
 const connectAckFile = process.env.SOOTSIM_PW_CONNECTED_ACK_FILE || '';
+const admittedFile = process.env.SOOTSIM_PW_ADMITTED_FILE || '';
 const completionFile = process.env.PEACH_PW_COMPLETION_FILE || '';
 const disposableBrowserCacheDirs = new Set(${JSON.stringify(
   DISPOSABLE_BROWSER_CACHE_DIR_NAMES,
@@ -121,6 +127,7 @@ const { tmpdir } = require('os');
 const { join } = require('path');
 const createBrowserPointerDispatcher = ${createBrowserPointerDispatcher.toString()};
 const automateWebViewFrames = ${automateWebViewFrames.toString()};
+const automateWebAuthenticationSessions = ${automateWebAuthenticationSessions.toString()};
 const webViewAutomationHelpers = ${webViewAutomationHelpersSource()};
 const readBrowserCompositeCaptureRequest = ${readBrowserCompositeCaptureRequest.toString()};
 const resolveBrowserCompositeCdpClip = ${resolveBrowserCompositeCdpClip.toString()};
@@ -402,6 +409,9 @@ const cleanupProfile = () => {
     if (connectAckFile) {
       try { unlinkSync(connectAckFile); } catch {}
     }
+    if (admittedFile) {
+      try { unlinkSync(admittedFile); } catch {}
+    }
     process.exit(code);
   };
   process.once('SIGTERM', () => { void shutdown(0); });
@@ -434,13 +444,25 @@ const cleanupProfile = () => {
       throw new Error('[playwright-driver] missing valid owning process; refusing unsupervised browser host');
     }
     const intervalMs = Number.isFinite(ownerPollMs) && ownerPollMs > 0 ? ownerPollMs : 5000;
-    ownerWatch = setInterval(() => {
+    const gone = (pid) => {
       try {
-        process.kill(ownerPid, 0);
+        process.kill(pid, 0);
+        return false;
       } catch (err) {
-        if (err && err.code === 'EPERM') return;
+        return !(err && err.code === 'EPERM');
+      }
+    };
+    ownerWatch = setInterval(() => {
+      if (gone(ownerPid)) {
         process.stderr.write('[owner-gone] owning process ' + ownerPid + ' exited; closing playwright host\\n');
         void shutdown(0);
+        return;
+      }
+      // until the sim connects, the open command is the only one waiting for
+      // it; once that command is gone nobody receives the sim.
+      if (!connected && !ackFileExists() && Number.isInteger(launcherPid) && launcherPid > 1 && gone(launcherPid)) {
+        process.stderr.write('[launcher-gone] open command ' + launcherPid + ' exited before the sim connected; closing playwright host\\n');
+        void shutdown(2);
       }
     }, intervalMs);
     if (typeof ownerWatch.unref === 'function') ownerWatch.unref();
@@ -479,6 +501,11 @@ const cleanupProfile = () => {
         LD_LIBRARY_PATH: [libraryPath, process.env.LD_LIBRARY_PATH].filter(Boolean).join(':'),
       };
     }
+    // keep the browser main process with its children in the caller's cgroup.
+    // otherwise chromium moves only main into a systemd app scope over dbus.
+    if (process.platform === 'linux') {
+      opts.env = { ...process.env, ...opts.env, ...${JSON.stringify(LINUX_CHROME_SCOPE_ENV)} };
+    }
     // playwright injects --force-color-profile=srgb by default, which reads
     // visibly washed-out next to a normal chrome window on a wide-gamut mac
     // display. strip it so driver-launched sims color-match the user's own
@@ -549,6 +576,11 @@ const cleanupProfile = () => {
     label: 'peach sim host ' + profileDir,
     readQueue: readChromiumQueue,
   });
+  // the launcher's connect wait starts here: time queued for the slot is not
+  // time the sim had to connect.
+  if (admittedFile) {
+    try { writeFileSync(admittedFile, JSON.stringify({ admittedAt: Date.now(), pid: process.pid }) + '\\n'); } catch {}
+  }
   clearStaleSingletonLock();
   let launchErr = null;
   let launchedChannel = null;
@@ -591,6 +623,8 @@ const cleanupProfile = () => {
   await context.grantPermissions(['camera']);
   const hostMeta = {
     sootsimHostDriver: 'playwright',
+    peachRenderer: hostCommand ? 'native' : 'chromium',
+    peachHostExecutable: hostCommand ? hostCommand[0] : null,
     sootsimHostPid: process.pid,
     sootsimHostOwnerPid: ownerPid,
     sootsimHostStartedAt: Date.now(),
@@ -677,6 +711,7 @@ const cleanupProfile = () => {
   }, Number.isFinite(connectTimeoutMs) && connectTimeoutMs > 0 ? connectTimeoutMs : 120000);
   if (typeof connectTimer.unref === 'function') connectTimer.unref();
   const page = await context.newPage();
+  await automateWebAuthenticationSessions(context, '__peachWebAuthenticationHost', page, !headless);
   if (hardwareGpuRequired) {
     assertNoUnsafeSwiftShaderFlag();
     const gpu = await page.evaluate(() => {

package/cli/drivers/playwright.ts

@@ -151,18 +151,15 @@ async function launch(opts: DriverLaunchOptions): Promise<DriverLaunchResult> {
   // renders natively and lets the page present only on capture; the host
   // reaches the browser over cdp, so it needs a debugging port.
   let hostCommand: string[] | null = null
-  if (headless && desktopHostPlatform()) {
+  if (headless && !opts.chromium && desktopHostPlatform()) {
     try {
       hostCommand = headlessHostCommand()
       if (!hostCommand && desktopHostPlatform() === 'linux-x64') {
-        // a missing or older host upgrades to the channel's current release; one published
-        // before the compatible headless host existed leaves this run on the browser engine alone
+        // delivery honors PEACH_DESKTOP_VERSION; a pin never follows channel latest.
         await desktopHostDelivery().install()
         hostCommand = headlessHostCommand()
         if (!hostCommand)
-          console.error(
-            '  native host release has no compatible headless host yet; rendering in the browser',
-          )
+          throw new Error('selected native host has no compatible headless entrypoint')
       }
     } catch (error) {
       return {
@@ -175,6 +172,7 @@ async function launch(opts: DriverLaunchOptions): Promise<DriverLaunchResult> {
 
   const errLog = join(tmpdir(), playwrightHostLogName(Date.now(), process.pid))
   const connectAckFile = `${errLog}.connected`
+  const admittedFile = `${errLog}.admitted`
   const completionFile = `${errLog}.completed`
   const errFd = openSync(errLog, 'a')
   try {
@@ -210,9 +208,11 @@ async function launch(opts: DriverLaunchOptions): Promise<DriverLaunchResult> {
             ? { SOOTSIM_PW_VIEWPORT: `${opts.viewport.width}x${opts.viewport.height}` }
             : {}),
           SOOTSIM_PW_CONNECTED_ACK_FILE: connectAckFile,
+          SOOTSIM_PW_ADMITTED_FILE: admittedFile,
           PEACH_PW_COMPLETION_FILE: completionFile,
           SOOTSIM_PW_CONNECT_TIMEOUT_MS: String(opts.connectTimeoutMs ?? 120_000),
           SOOTSIM_PW_OWNER_PID: String(ownerPid),
+          SOOTSIM_PW_LAUNCHER_PID: String(process.pid),
           SOOTSIM_PW_LIBRARY_PATH: provisioning.libraryPath ?? '',
         },
       },
@@ -233,11 +233,12 @@ async function launch(opts: DriverLaunchOptions): Promise<DriverLaunchResult> {
     const ownerNote = ` — browser closes when pid ${ownerPid}${ownerComm ? ` (${ownerComm})` : ''} exits, or after ${idleMinutes} min with no peach command or input if another browser launch is waiting for its slot`
     return {
       launched: true,
-      message: `playwright chrome launched → ${targetUrl.href}${ownerNote}`,
+      message: `playwright ${hostCommand ? 'native host' : 'Chromium'} launched → ${targetUrl.href}${ownerNote}`,
       pid: child.pid,
       target: resolved.spec,
       attachUrl: targetUrl.href,
       connectAckFile,
+      admittedFile,
       diagnosticLogPath: errLog,
       completion,
       completionFile,
@@ -257,7 +258,7 @@ async function launch(opts: DriverLaunchOptions): Promise<DriverLaunchResult> {
 export const playwrightDriver: Driver = {
   id: 'playwright',
   name: 'playwright',
-  description: 'programmatic chromium via the playwright package — headless default',
+  description: 'isolated Chromium; headless uses the native host when available',
   kind: 'automation',
   availability: probe,
   launch,

package/cli/drivers/types.ts

@@ -30,6 +30,8 @@ export interface DriverLaunchOptions {
   url?: string
   // run in headless mode where the driver supports it. ignored by electron.
   headless?: boolean
+  // opt this open into browser rendering without acquiring or attaching a native host.
+  chromium?: boolean
   // initial device model seed forwarded to the peach shell. the electron
   // driver forwards it via argv (--device=<model>); browser drivers receive
   // it already stamped on the URL (?device=<model>) by runOpenCommand.
@@ -86,6 +88,9 @@ export interface DriverLaunchResult {
   target?: string
   attachUrl?: string
   connectAckFile?: string
+  // written once the host holds its machine-wide browser slot; its connect
+  // budget starts there, so the launcher's wait starts there too.
+  admittedFile?: string
   diagnosticLogPath?: string
   // foreground guest hosts await the detached driver's exit without polling.
   completion?: Promise<DriverCompletion>

package/cli/maestro-accessibility.ts

@@ -1,7 +1,7 @@
 import type { PeachAccessibilityNode } from '@peach/globals'
 
 // maestro reads ios frames as integer edges (AXElement.boundsString).
-export function accessibilityBounds(node: PeachAccessibilityNode): {
+export function accessibilityBounds(node: Pick<PeachAccessibilityNode, 'frame'>): {
   x: number
   y: number
   width: number