peachsim 0.1.939 → 0.1.1399

package/README.md

@@ -95,7 +95,7 @@ graph TD
     TENANTW["tenant worker (guest RN app tree)"]
   end
   subgraph build["build-time plugins (src/)"]
-    VITEONE["peachsim/vite = vite-plugin-one.ts (serve runtime at /__soot/)"]
+    VITEONE["peachsim/vite = vite-plugin-one.ts (serve runtime at /__peachsim/)"]
     VITERN["sootsim() = vite-plugin.ts (RN resolver + native stubs)"]
     METRO["peachsim/metro = metro-plugin.ts"]
     COMPAT["@sootsim/compat stub-manifest (native seams)"]
@@ -139,8 +139,8 @@ graph TD
   RTHTTP -->|"manifest + tarball"| CDN
   DRIVERS -->|"open sim page URL"| SHELLW
   SHELLW -->|"NativeUIRequest"| TENANTW
-  VITEONE -->|"serve /__soot/ from"| RTDIR
-  METRO -->|"serve /__soot/ from"| RTDIR
+  VITEONE -->|"serve /__peachsim/ from"| RTDIR
+  METRO -->|"serve /__peachsim/ from"| RTDIR
   VITEONE -.->|"launch electron app"| SHELLW
   VITERN -->|"alias react-native"| ENGINESHIM
   VITERN -->|"alias native pkgs"| COMPAT
@@ -165,7 +165,7 @@ An explicit `--base-url` keeps that shell's origin and uses its assets without
 installing an active runtime. A bridge started for that shell skips automatic
 runtime updates. An app's configured `runtimeVersion` still selects its installed,
 version-owned bridge origin.
-Electron is the native desktop surface. Team Machine sessions (`TM_SESSION`)
+The native host supplies the desktop surface on Mac and Linux; Electron is Windows-only. Team Machine sessions (`TM_SESSION`)
 default to headless Playwright; `--headed` explicitly opens an isolated headed
 browser. System browser launches, including share links, login, box links and
 repo scripts, go through `src/host/open-url.ts`. That owner refuses a system
@@ -203,9 +203,9 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 
 **Two distinct plugin families** round it out, and they must not be conflated:
 
-- The published **`peachsim/vite`** (`src/vite-plugin-one.ts`, `rnxPlugin`)
+- The published **`peachsim/vite`** (`src/vite-plugin-one.ts`, `peachPlugin`)
   and **`peachsim/metro`** plugins do one thing: serve the installed runtime at
-  `/__soot/` so an app's own dev server can host the sim shell. The Vite plugin accepts an
+  `/__peachsim/` so an app's own dev server can host the sim shell. The Vite plugin accepts an
   opt-in `open` option that launches a named Electron window when the dev server
   starts (skipped when `CI` or `PEACH_NO_OPEN` is set).
 - The internal **`sootsim()`** plugin (`src/vite-plugin.ts`) is a separate, much
@@ -236,13 +236,13 @@ the later trace URL notifies viewers without extending that duration.
 Maestro YAML header `onFlowStart` and `onFlowComplete` hooks reach the same
 runner as body hooks, including nested `runFlow` files. A header reset flow
 therefore runs before assertions in each flow.
-| sim drivers | Launch or attach the actual sim page. Playwright owns isolated browser profiles; Electron owns the native desktop surface. The current sim is reused unless `--new`, `--profile`, or `--ephemeral` requests a separate one. | `cli/drivers/index.ts`, `cli/drivers/registry.ts`, `cli/drivers/electron.ts`, `cli/drivers/playwright.ts` |
+| sim drivers | Launch or attach the actual sim page. Playwright owns isolated browser profiles; the native host owns Mac and Linux desktop windows; Electron owns Windows windows. The current sim is reused unless `--new`, `--profile`, or `--ephemeral` requests a separate one. | `cli/drivers/index.ts`, `cli/drivers/registry.ts`, `cli/drivers/electron.ts`, `cli/drivers/playwright.ts` |
 | SootSimBridgeHost (serve/daemon) | The bridge process (`peach serve`, or autostarted as the daemon via launchd/systemd). HTTP+WS hub on `:7668`: relays commands between CLI clients and registered sims; also serves runtime HTTP, `/__server-scan`, and fetch/WS proxies. | `src/host/bridge-host.ts`, `cli/commands/serve.ts`, `cli/commands/daemon.ts`, `src/home-paths.ts` |
 | AgentHost + sessions | Agent-routing extension of the host: owns the single FIFO reader per agent session and fans `agent:event`/`session-status` pushes to every WS subscriber. Backed by agent-sessions + attached-projects stores. | `src/host/agent-host.ts`, `src/agent-sessions.ts`, `src/attached-projects.ts`, `src/agent-daemon-client.ts` |
 | host proxies + dev-server scan | Host-side helpers so a cross-origin tenant worker can reach local dev servers and same-origin APIs: `/__server-scan` discovers running metro/expo/vxrn/one servers; fetch + websocket proxies relay guest-app network through the daemon. | `src/host/fetch-proxy-handler.ts`, `src/host/websocket-proxy.ts`, `scripts/dev-server-scanner.ts`, `src/dev-bundle-resolution.ts` |
 | runtime delivery + Peach home | Versioned engine runtime management. The shared machinery owns manifest fetch, sha256 verification, channels, and auto-update. Peach binds it to `https://contrast.dev` and `~/.peach/runtimes/<version>`. A repo can select `runtimeVersion` without changing the machine default. | `src/runtime-delivery.ts`, `packages/contrast-runtime-delivery/`, `src/home-paths.ts`, `src/runtime-assets.ts` |
 | standalone CLI delivery | Cached stable-version checks, bounded interactive notices, and verified atomic executable replacement. | `cli/cli-update.ts`, `cli/commands/upgrade.ts`, `cli/commands/version.ts`, `src/cli-version.ts` |
-| `peachsim/vite` + `peachsim/metro` (runtime serving) | Published bundler plugins. Both serve the installed engine runtime at `/__soot/` from `~/.peach/runtimes/<version>` so an app's own dev server can host the sim shell; the Vite plugin can opt into a named Electron window. | `src/vite-plugin-one.ts`, `src/metro-plugin.ts`, `src/runtime-assets.ts` |
+| `peachsim/vite` + `peachsim/metro` (runtime serving) | Published bundler plugins. Both serve the installed engine runtime at `/__peachsim/` from `~/.peach/runtimes/<version>` so an app's own dev server can host the sim shell; the Vite plugin can opt into a named Electron window. | `src/vite-plugin-one.ts`, `src/metro-plugin.ts`, `src/runtime-assets.ts` |
 | `sootsim()` vite resolver plugin (internal) | The large RN-resolution / native-stub vite plugin: aliases `react-native` to the engine shim, native packages to `@sootsim/compat` stubs, applies worklets/babel transforms, and instantiates `SootSimBridgeHost` in its dev server. Distinct from the published `peachsim/vite` export. | `src/vite-plugin.ts`, `src/worklets-babel.ts`, `packages/peach-compat/src/stub-manifest.ts` |
 | skills registry | Peach agent skills (`peach-setup`, `peach-debug`, `peach-test`, `peach-visual`, and the generated `contrast` index) installable with `peach skill`. | `skills/*.md`, `src/skills/registry.ts`, `src/skills/types.ts` |
 
@@ -418,7 +418,7 @@ peach detox             # run Detox/Jest suites against Peach
 ```
 
 See the full command reference via `peach --help` or at
-`src/features/site/docs/rnx/cli/` in the Contrast repo.
+`src/features/site/docs/peach/cli/` in the Contrast repo.
 
 Sim-scoped commands use the primary fallback only when one driveable sim is
 connected. With multiple driveable sims, the bridge lists their ids and refuses
@@ -441,21 +441,21 @@ The Vite plugin serves the installed Peach runtime from your existing dev server
 
 ```ts
 // vite.config.ts
-import { rnxPlugin } from 'peachsim/vite'
+import { peachPlugin } from 'peachsim/vite'
 
 export default {
-  plugins: [rnxPlugin({ open: { appName: 'My App' } })],
+  plugins: [peachPlugin({ open: { appName: 'My App' } })],
 }
 ```
 
 ```js
 // metro.config.js
 const { getDefaultConfig } = require('expo/metro-config')
-const { withRNX } = require('peachsim/metro')
+const { withPeach } = require('peachsim/metro')
 
 const config = getDefaultConfig(__dirname)
 
-module.exports = withRNX(config)
+module.exports = withPeach(config)
 ```
 
 Peach works directly with regular, unannotated Metro production JavaScript bundles
@@ -465,7 +465,7 @@ a supported input; pass Peach the JavaScript bundle produced before Hermes
 compilation.
 
 If an app has unusual dependencies or fingerprint inference fails, you can
-optionally wrap your Metro configuration with `withRNX(config)`. It takes no
+optionally wrap your Metro configuration with `withPeach(config)`. It takes no
 options and enables two integrations:
 
 1. **Deterministic module identity:** appends Metro's exact module identity map
@@ -473,7 +473,7 @@ options and enables two integrations:
    bundle. Resolution, transforms, minification, and source maps stay the app's
    own, so the annotated bundle is the exact bundle you ship: the footer assigns
    one unused global on a device, and Hermes drops it during bytecode compilation.
-2. **In-browser dev shell:** serves the Peach simulator shell at `/__soot/` on
+2. **In-browser dev shell:** serves the Peach simulator shell at `/__peachsim/` on
    the Metro dev server.
 
 The URL helpers request ordinary Metro graphs: `dev=false&minify=true` for
@@ -481,14 +481,14 @@ production and `dev=true&minify=false` for development.
 
 ```js
 const {
-  toRNXProductionBundleUrl,
-  toRNXDevelopmentBundleUrl,
+  toPeachProductionBundleUrl,
+  toPeachDevelopmentBundleUrl,
 } = require('peachsim/metro')
 
-const productionUrl = toRNXProductionBundleUrl(
+const productionUrl = toPeachProductionBundleUrl(
   'http://localhost:8081/index.bundle?platform=ios',
 )
-const developmentUrl = toRNXDevelopmentBundleUrl(
+const developmentUrl = toPeachDevelopmentBundleUrl(
   'http://localhost:8081/index.bundle?platform=ios',
 )
 ```
@@ -629,12 +629,12 @@ the generated `contrast` command index. The published CLI registry and generated
 website docs both come from `packages/peach-skills/`:
 
 - `packages/peachsim/skills/contrast/SKILL.md` is generated from that registry
-- `src/features/site/docs/rnx/cli/*` is generated output, not hand-edited
+- `src/features/site/docs/peach/cli/*` is generated output, not hand-edited
 
 When command docs or examples drift, update `packages/peach-skills/` and run:
 
 ```sh
-bun run generate:sootsim-docs
+bun run generate:peach-docs
 ```
 
 ## Runtime delivery (the Peach home and CDN)
@@ -650,7 +650,7 @@ verifies its sha256, and unpacks it under `~/.peach`:
 ```
 ~/.peach/
 ├── runtimes/
-│   ├── <active>/         unpacked engine assets (served at /__soot/)
+│   ├── <active>/         unpacked engine assets (served at /__peachsim/)
 │   └── <rollback>/       previous version for rollback
 ├── cache/                legacy downloads; empty after cleanup
 ├── profiles/             persistent named app storage, without browser caches
@@ -691,6 +691,12 @@ CLI's cwd is never an asset/config fallback. Asset wires stay on each opened
 project URL, so one daemon can serve several attached projects without sharing
 font or splash state between them.
 
+Bare iOS projects carry default Firebase options from their selected app
+target's Google services build resource when the app delegate initializes
+Firebase unconditionally during launch. Completed compile conditional blocks
+before that call are allowed. Initialization inside an open conditional block
+or after a possible early return is rejected.
+
 The first interactive CLI command after this cleanup generation finishes its
 requested work, then launches the same safe default plan in a detached
 maintenance process. The app and terminal command are usable before the legacy

package/cli/app-catalog.ts

@@ -1,6 +1,9 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { enumerateBundleColors } from '../../sootsim-swift/src/bundleAssets'
+import {
+  enumerateBundleColors,
+  enumerateBundleImages,
+} from '../../sootsim-swift/src/bundleAssets'
 import type { AppCatalog } from 'peach-engine/engine/app-catalog-wire'
 
 // the xcode build setting actool turns into the built Info.plist's
@@ -33,12 +36,16 @@ function catalogFiles(dir: string, found: string[]) {
   }
 }
 
-// the app's asset-catalog colors and its declared accent, read off the ios
-// project a prebuild or a bare app keeps on disk: the app target is the
-// folder holding the AppDelegate, the catalogs are its .xcassets, and the
-// accent is what its Info.plist or project build settings name. null when
-// the app has no ios project on disk or declares neither.
-export function discoverAppCatalog(appDir: string): AppCatalog | null {
+// the app's asset-catalog colors and images and its declared accent, read off
+// the ios project a prebuild or a bare app keeps on disk: the app target is
+// the folder holding the AppDelegate, the catalogs are its .xcassets, and the
+// accent is what its Info.plist or project build settings name. metro serves
+// each picked raster at `<origin>/assets/<project-relative-path>`. null when
+// the app has no ios project on disk or declares none of them.
+export function discoverAppCatalog(
+  appDir: string,
+  metroOrigin: string,
+): AppCatalog | null {
   const iosDir = path.join(appDir, 'ios')
   const target = listDir(iosDir).find(
     (entry) =>
@@ -58,11 +65,14 @@ export function discoverAppCatalog(appDir: string): AppCatalog | null {
   const relative = files.map((file) =>
     path.relative(targetDir, file).split(path.sep).join(path.posix.sep),
   )
-  const colors = enumerateBundleColors(relative, (candidate) =>
-    candidate.endsWith('Contents.json')
-      ? readText(path.join(targetDir, candidate))
-      : null,
-  )
+  const readContents = (candidate: string) =>
+    candidate.endsWith('Contents.json') ? readText(path.join(targetDir, candidate)) : null
+  const colors = enumerateBundleColors(relative, readContents)
+  const served = path.relative(appDir, targetDir).split(path.sep).join(path.posix.sep)
+  const images: AppCatalog['images'] = {}
+  for (const { name, file, scale } of enumerateBundleImages(relative, readContents)) {
+    ;(images[name] ??= []).push({ uri: `${metroOrigin}/assets/${served}/${file}`, scale })
+  }
   const pbxproj = listDir(iosDir).find((entry) => entry.name.endsWith('.xcodeproj'))
   const accentName =
     readText(path.join(targetDir, 'Info.plist'))?.match(PLIST_ACCENT)?.[1] ??
@@ -72,6 +82,11 @@ export function discoverAppCatalog(appDir: string): AppCatalog | null {
         )?.[1]
       : undefined) ??
     null
-  if (accentName === null && Object.keys(colors).length === 0) return null
-  return { colors, accentName }
+  if (
+    accentName === null &&
+    Object.keys(colors).length === 0 &&
+    Object.keys(images).length === 0
+  )
+    return null
+  return { colors, images, accentName }
 }

package/cli/app-fonts.ts

@@ -305,10 +305,12 @@ export async function resolveMetroProjectRoot(
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 1500)
   let servedManifest = false
+  let metroRunning = false
   try {
     const status = await fetch(`${origin}/status`, { signal: controller.signal })
     const advertisedRoot = status.headers.get('X-React-Native-Project-Root')
     if (status.ok && advertisedRoot) return decodeURI(advertisedRoot)
+    metroRunning = status.ok && (await status.text()).trim() === 'packager-status:running'
     const res = await fetch(`${origin}/`, {
       headers: { 'expo-platform': 'ios', Accept: 'application/json' },
       signal: controller.signal,
@@ -330,9 +332,9 @@ export async function resolveMetroProjectRoot(
   // knows. if it did not name a project root there is none to learn, and asking
   // the OS about the listening process would answer with whatever directory
   // that process happens to sit in — which is the CLI's own cwd trap this
-  // function exists to avoid. only a server that served no manifest at all gets
-  // the process lookup.
-  if (servedManifest) return null
+  // function exists to avoid. only a server whose status identifies Metro
+  // and which served no manifest gets the process lookup.
+  if (servedManifest || !metroRunning) return null
 
   const port = Number(new URL(origin).port)
   if (!Number.isFinite(port) || port <= 0) return null

package/cli/bridge-flow-runner.ts

@@ -548,6 +548,12 @@ export type SootSimFlowTraceStep = {
   screenshotPath?: string
 }
 
+export type SootSimFlowConsole = {
+  errors: unknown[]
+  warnings: unknown[]
+  requests: unknown[]
+}
+
 export interface MaestroStep {
   tapOn?:
     | string
@@ -2135,6 +2141,24 @@ export class SootSimBridgeFlowRunner {
     return model as DeviceModel
   }
 
+  // the app's console errors and warnings plus failed requests, captured by
+  // peach's native-globals hook and request recorder (same shape as
+  // `peach get errors`).
+  async readConsole(): Promise<SootSimFlowConsole> {
+    return (await this.bridge.send({
+      type: 'evaluate',
+      simId: this.opts.simId,
+      code: `(() => {
+        const c = window.__sootsimConsole
+        return {
+          errors: c?.getErrors?.() ?? [],
+          warnings: c?.getWarnings?.() ?? [],
+          requests: (window.__sootsimGetFailedRequests?.() ?? []),
+        }
+      })()`,
+    })) as SootSimFlowConsole
+  }
+
   async captureScreenshot(outputPath: string) {
     await this.takeScreenshot({ path: outputPath })
   }
@@ -2262,20 +2286,8 @@ export class SootSimBridgeFlowRunner {
     )
     if (typeof tree === 'string') write('tree.txt', tree)
 
-    // 6. console buffer + failed requests (captured by peach's native-globals
-    // hook / request recorder; same shape as `peach get errors` etc.).
-    const consoleBuf = await safeEval<{
-      errors: unknown[]
-      warnings: unknown[]
-      requests: unknown[]
-    } | null>(`(() => {
-      const c = window.__sootsimConsole
-      return {
-        errors: c?.getErrors?.() ?? [],
-        warnings: c?.getWarnings?.() ?? [],
-        requests: (window.__sootsimGetFailedRequests?.() ?? []),
-      }
-    })()`)
+    // 6. console buffer + failed requests
+    const consoleBuf = await this.readConsole().catch(() => null)
     if (consoleBuf) {
       write('console.json', JSON.stringify(consoleBuf, null, 2))
     }
@@ -2418,20 +2430,21 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
+  // maestro's waitForAnimationToEnd compares screenshots until the screen holds
+  // still, so motion the screen does not show (an endless loop under a
+  // full-screen sheet) never holds it; visible shell motion changes the pixels.
+  // like maestro, a screen that never holds still (a looping illustration)
+  // ends the wait at the timeout and the flow continues
   async waitForAnimationToEnd(timeoutMs: number = 2000) {
     const maxMs = Math.max(0, Math.round(timeoutMs))
     if (maxMs <= 0) return
-    const result = await waitForSootsimIdle({
+    await waitForSootsimIdle({
       bridge: this.bridge,
       simId: this.opts.simId,
       maxMs,
       pollMs: 32,
-      stablePolls: 2,
-      strict: true,
+      paintStill: true,
     })
-    if (!result.settled) {
-      throw new Error(`animation did not settle within ${maxMs}ms`)
-    }
   }
 
   async back() {
@@ -3411,7 +3424,7 @@ export class SootSimBridgeFlowRunner {
     this.lastFailedStep = null
   }
 
-  extractFlowBody(steps: MaestroStep[]) {
+  extractFlowBody(steps: (MaestroStep | string)[]) {
     // maestro `onFlowStart` / `onFlowComplete` lifecycle hooks: if any step
     // in the array is a sole-key entry whose key is one of these names and
     // whose value is a list of sub-steps, pull them out and run them as
@@ -3419,7 +3432,9 @@ export class SootSimBridgeFlowRunner {
     const onStart: MaestroStep[] = []
     const onComplete: MaestroStep[] = []
     const body: MaestroStep[] = []
-    for (const step of steps) {
+    for (const rawStep of steps) {
+      const step =
+        typeof rawStep === 'string' ? normalizeBareStringStep(rawStep) : rawStep
       const keys = Object.keys(step)
       if (
         keys.length === 1 &&
@@ -3442,15 +3457,11 @@ export class SootSimBridgeFlowRunner {
     return { onStart, onComplete, body }
   }
 
-  async planFlow(steps: MaestroStep[], options: { dryRun?: boolean } = {}) {
+  async planFlow(steps: (MaestroStep | string)[], options: { dryRun?: boolean } = {}) {
     const { body } = this.extractFlowBody(steps)
     if (this.liveStatus) {
       await this.liveStatus.plan(
-        body.map((rawStep, index) => {
-          // yaml parses bare-string steps (`- back`) as strings; mirror
-          // runStep's normalization so the rail shows the verb, not chars.
-          const step =
-            typeof rawStep === 'string' ? normalizeBareStringStep(rawStep) : rawStep
+        body.map((step, index) => {
           const name = Object.keys(step).find((k) => k !== 'when') ?? Object.keys(step)[0]
           return { index, name, target: this.flowStepTargetLabel(step, name) }
         }),
@@ -3459,7 +3470,7 @@ export class SootSimBridgeFlowRunner {
     }
   }
 
-  async runFlow(steps: MaestroStep[], options: { skipPlan?: boolean } = {}) {
+  async runFlow(steps: (MaestroStep | string)[], options: { skipPlan?: boolean } = {}) {
     const { onStart, onComplete, body } = this.extractFlowBody(steps)
     this.lastInteractionAt = Date.now()
 

package/cli/cloud-client.ts

@@ -8,6 +8,7 @@ import {
   readFileSync,
 } from 'node:fs'
 import { dirname, extname, join, resolve } from 'node:path'
+import { Script } from 'node:vm'
 import {
   embedMetroAssetFiles,
   extractAssetDescriptors,
@@ -256,10 +257,21 @@ async function loadBundleSource(bundleInput: string): Promise<string> {
   if (bundleInput.startsWith('http://') && !isLoopbackBundleUrl(bundleInput)) {
     throw new Error(`${REMOTE_COMMAND} bundle URL must use HTTPS`)
   }
-  if (isRemoteBundleInput(bundleInput)) {
-    return fetchBundleSource(bundleInput)
+  const source = isRemoteBundleInput(bundleInput)
+    ? await fetchBundleSource(bundleInput)
+    : readImmutableBundleSource(bundleInput)
+  // a box evaluates the bundle as a script; refuse invalid syntax before
+  // allocating a billable host. compiling does not execute guest code.
+  try {
+    new Script(source, { filename: bundleInput })
+  } catch (error) {
+    throw new Error(
+      `${REMOTE_COMMAND} bundle contains invalid JavaScript: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
   }
-  return readImmutableBundleSource(bundleInput)
+  return source
 }
 
 // `react-native bundle --assets-dest` dest paths are not always the JS
@@ -536,16 +548,19 @@ function unverifiedContentKey(
 function searchMetroAssetDest(
   bundlePath: string,
   descriptors: readonly MetroAssetDescriptor[],
+  assetsDirectory?: string,
 ): MetroAssetSearch {
   const bundleDirectory = dirname(resolve(bundlePath))
-  const candidates = [
-    join(bundleDirectory, 'assets'),
-    bundleDirectory,
-    resolve(bundleDirectory, '..', 'assets'),
-  ]
+  const candidates = assetsDirectory
+    ? [resolve(assetsDirectory)]
+    : [
+        join(bundleDirectory, 'assets'),
+        bundleDirectory,
+        resolve(bundleDirectory, '..', 'assets'),
+      ]
   const cwd = process.cwd()
   let projectDirectory: string | null = null
-  for (const start of [bundleDirectory, cwd]) {
+  for (const start of assetsDirectory ? [] : [bundleDirectory, cwd]) {
     let directory = resolve(start)
     while (true) {
       if (detectProject(directory)?.hasMetroConfig) {
@@ -653,7 +668,7 @@ async function inferCloudModuleIdentity(
     throw new Error(
       `${REMOTE_COMMAND} could not load the Metro fingerprint registry needed to identify this bundle: ${
         error instanceof Error ? error.message : String(error)
-      }. Build it through the published Metro plugin: withRNX(config).`,
+      }. Build it through the published Metro plugin: withPeach(config).`,
     )
   }
   try {
@@ -672,7 +687,7 @@ async function inferCloudModuleIdentity(
     throw new Error(
       `${REMOTE_COMMAND} could not infer module identity for this Metro bundle: ${
         error instanceof Error ? error.message : String(error)
-      }. Build it through the published Metro plugin: withRNX(config).`,
+      }. Build it through the published Metro plugin: withPeach(config).`,
     )
   }
 }
@@ -682,7 +697,7 @@ async function inferCloudModuleIdentity(
  * the runner executes: every asset scale is read from the asset graph and
  * embedded, module identity is normalized, and the JavaScript is minified.
  * an ordinary unannotated Metro production bundle is identified through the
- * published fingerprint registry; a withRNX footer remains the fast path.
+ * published fingerprint registry; a withPeach footer remains the fast path.
  */
 export interface CloudArtifactProduction {
   bytes: Buffer
@@ -701,8 +716,15 @@ export async function produceCloudArtifact(
    * the default; a box that accepts a larger artifact passes its own.
    */
   maxBytes: number = MAX_RNX_CLOUD_BUNDLE_BYTES,
+  assetsDirectory?: string,
 ): Promise<CloudArtifactProduction> {
-  return produceArtifact(bundlePath, maxBytes, REMOTE_COMMAND, 'allow-placeholders')
+  return produceArtifact(
+    bundlePath,
+    maxBytes,
+    REMOTE_COMMAND,
+    assetsDirectory ? 'require-assets' : 'allow-placeholders',
+    assetsDirectory,
+  )
 }
 
 /** prepares a standalone preview whose bytes must represent every Metro asset. */
@@ -726,11 +748,13 @@ export interface CloudBoxArtifactProduction {
 /** prepares a prebuilt bundle for a Box by embedding any beside-the-bundle Metro assets. */
 export async function produceCloudBoxArtifact(
   bundlePath: string,
+  assetsDirectory?: string,
 ): Promise<CloudBoxArtifactProduction> {
   const prepared = await embedBundleAssets(
     bundlePath,
     'peach box create',
-    'allow-placeholders',
+    assetsDirectory ? 'require-assets' : 'allow-placeholders',
+    assetsDirectory,
   )
   const warnings: string[] = []
   if (prepared.search.unconfirmed && prepared.dest) {
@@ -754,6 +778,7 @@ async function embedBundleAssets(
   bundlePath: string,
   command: string,
   assetPolicy: 'allow-placeholders' | 'require-assets',
+  assetsDirectory?: string,
 ): Promise<{
   source: string
   code: string
@@ -774,11 +799,11 @@ async function embedBundleAssets(
       substituted: [],
     }
   }
-  // an https bundle has no local tree to search, and a bundle with no assets
-  // has nothing to search for.
-  const search: MetroAssetSearch = !isRemoteBundleInput(bundlePath)
-    ? searchMetroAssetDest(bundlePath, descriptors)
-    : { dest: null, searched: [], truncated: false, unconfirmed: false }
+  // an https bundle uses only an explicit local asset destination.
+  const search: MetroAssetSearch =
+    assetsDirectory || !isRemoteBundleInput(bundlePath)
+      ? searchMetroAssetDest(bundlePath, descriptors, assetsDirectory)
+      : { dest: null, searched: [], truncated: false, unconfirmed: false }
   const dest = search.dest
   // `embedMetroAssetFiles` re-parses the bundle, so its descriptors are equal
   // to the ones the search placed but not the same objects.
@@ -854,8 +879,14 @@ async function produceArtifact(
   maxBytes: number,
   command: string,
   assetPolicy: 'allow-placeholders' | 'require-assets',
+  assetsDirectory?: string,
 ): Promise<CloudArtifactProduction> {
-  const prepared = await embedBundleAssets(bundlePath, command, assetPolicy)
+  const prepared = await embedBundleAssets(
+    bundlePath,
+    command,
+    assetPolicy,
+    assetsDirectory,
+  )
   const artifact = await buildRnxCloudArtifact(prepared.code, {
     inferModuleIdentity: inferCloudModuleIdentity,
   })
@@ -1040,6 +1071,7 @@ export async function createCloudBox(options: CreateCloudBoxOptions): Promise<{
 
 export interface CreateRemoteSimOptions {
   bundlePath: string
+  assetsDirectory?: string
   device: string
   authorization: string
   /** the account to bill when the authorization is a session token; an api key names its own */
@@ -1110,7 +1142,11 @@ export async function createRemoteSim(options: CreateRemoteSimOptions): Promise<
   reused: boolean
 }> {
   const apiOrigin = resolveCloudOrigin(options.apiOrigin)
-  const artifact = await produceCloudArtifact(options.bundlePath)
+  const artifact = await produceCloudArtifact(
+    options.bundlePath,
+    undefined,
+    options.assetsDirectory,
+  )
   const query = new URLSearchParams({
     labels: `peach.remote=1,peach.platform=${options.platform},peach.bundle=${artifact.sha256.slice(0, 12)}`,
     wait: 'true',

package/cli/cloud-test-tunnel.ts

@@ -110,7 +110,7 @@ export function startCloudTestTokenProxy(
   upstreamPort: number,
   sidecarPorts: readonly number[],
   token: string,
-): Promise<{ close: () => void } | null> {
+): Promise<{ port: number; close: () => void } | null> {
   const server = createServer((req, res) => {
     const auth = req.headers.authorization || ''
     if (auth !== `Bearer ${token}`) {
@@ -177,7 +177,11 @@ export function startCloudTestTokenProxy(
   return new Promise((resolve) => {
     server.on('error', () => resolve(null))
     server.listen(listenPort, '127.0.0.1', () => {
-      resolve({ close: () => server.close() })
+      const address = server.address()
+      if (!address || typeof address !== 'object') {
+        throw new Error('token proxy has no listening address')
+      }
+      resolve({ port: address.port, close: () => server.close() })
     })
   })
 }
@@ -187,7 +191,7 @@ function cloudflaredAvailable(): boolean {
   return probe.status === 0
 }
 
-async function ensureCloudflared(): Promise<boolean> {
+export async function ensureCloudflared(): Promise<boolean> {
   if (cloudflaredAvailable()) return true
   const archMap: Record<string, string> = { x64: 'amd64', arm64: 'arm64' }
   const arch = archMap[process.arch]
@@ -232,7 +236,7 @@ function childAlive(child: ChildProcess): boolean {
   return child.exitCode === null && child.signalCode === null
 }
 
-async function launchQuickTunnel(
+export async function launchQuickTunnel(
   originUrl: string,
   hostHeader: string,
   logFile: string,
@@ -297,23 +301,13 @@ export async function publishLiveDevStack(args: {
 }): Promise<PublishedLiveDevStack> {
   const { devPort, sidecarPorts } = args
   const jobToken = randomBytes(16).toString('hex')
-  // free loopback port for the token proxy; the advertised authority stays
+  // let the token proxy own its port; the advertised authority stays
   // the dev server's own port so Metro URLs resolve on the recorder.
-  const { Server } = await import('node:net')
-  const proxyPort = await new Promise<number>((resolve, reject) => {
-    const probe = new Server()
-    probe.once('error', reject)
-    probe.listen(0, '127.0.0.1', () => {
-      const address = probe.address()
-      const port = address && typeof address === 'object' ? address.port : 0
-      probe.close(() => resolve(port))
-    })
-  })
-  if (!proxyPort) throw new Error('could not allocate a tunnel proxy port')
-  const proxy = await startCloudTestTokenProxy(proxyPort, devPort, sidecarPorts, jobToken)
+  const proxy = await startCloudTestTokenProxy(0, devPort, sidecarPorts, jobToken)
   if (!proxy) {
-    throw new Error(`could not start the tunnel token proxy on 127.0.0.1:${proxyPort}`)
+    throw new Error('could not start the tunnel token proxy on 127.0.0.1')
   }
+  const proxyPort = proxy.port
   const closeProxy = proxy.close
   const hostHeader = `127.0.0.1:${devPort}`
   if (!(await ensureCloudflared())) {

package/cli/commands/agent.ts

@@ -37,7 +37,7 @@ import type { AgentEvent } from '../../src/agent-events'
 import type { AgentInspectMessage } from '../../src/agent-prompt'
 
 // the bridge this invocation talks to: `-p`, else the same dev-bridge or
-// daemon pick every other command makes (PORT_OFFSET and SOOTSIM_BRIDGE_PORT
+// daemon pick every other command makes (PORT_OFFSET and PEACH_BRIDGE_PORT
 // included).
 let daemonPort = 0