peachsim 0.1.939 → 0.1.1399

package/cli/commands/detect.ts

@@ -5,6 +5,7 @@ import { basename, dirname, join } from 'node:path'
 import JSON5 from 'json5'
 import { parse as parseYaml } from 'yaml'
 import { nodeRepoFileReader } from './nodeRepoFileReader'
+import type { NativeRenderer } from '../../src/config'
 import type { DependencyVersion, ProjectManifest } from './projectReportContract'
 import type { RepoFileReader } from './repoFileReaderContract'
 
@@ -479,3 +480,103 @@ export function installedManifest(
     devDependencies: mapped(manifest.devDependencies),
   }
 }
+
+// read only explicit static native build settings for the selected platform.
+export function readNativeProjectRenderer(
+  dir: string,
+  platform: 'ios' | 'android',
+  files: RepoFileReader = nodeRepoFileReader,
+): NativeRenderer | undefined {
+  const declarations: Array<{ source: string; enabled: boolean }> = []
+  const add = (value: unknown, source: string, strings = false) => {
+    if (value === undefined) return
+    if (typeof value === 'boolean') declarations.push({ source, enabled: value })
+    else if (strings && (value === 'true' || value === 'false'))
+      declarations.push({ source, enabled: value === 'true' })
+    else throw new Error(`${source}: new architecture setting must be true or false`)
+  }
+  const json = (path: string): unknown => {
+    const text = readProjectMetadata(join(dir, path), files)
+    if (text === null) {
+      if (files.exists(join(dir, path)))
+        throw new Error(`${path}: unreadable native metadata`)
+      return undefined
+    }
+    try {
+      return JSON.parse(text)
+    } catch {
+      throw new Error(`${path}: malformed native metadata`)
+    }
+  }
+  const expo = metadataValue(json('app.json'), 'expo')
+  add(metadataValue(expo, 'newArchEnabled'), 'app.json expo.newArchEnabled')
+  add(
+    metadataValue(metadataValue(expo, platform), 'newArchEnabled'),
+    `app.json expo.${platform}.newArchEnabled`,
+  )
+  if (platform === 'ios') {
+    add(
+      metadataValue(json('ios/Podfile.properties.json'), 'newArchEnabled'),
+      'ios/Podfile.properties.json newArchEnabled',
+      true,
+    )
+    const podfile = readProjectMetadata(join(dir, 'ios/Podfile'), files)
+    if (podfile === null && files.exists(join(dir, 'ios/Podfile')))
+      throw new Error('ios/Podfile: unreadable native metadata')
+    for (const line of (podfile ?? '').split(/\r?\n/)) {
+      // use_react_native!(new_arch_enabled: false) assigns RCT_NEW_ARCH_ENABLED
+      // itself; a non-literal argument defers to the declarations read here.
+      const argument =
+        /^\s*(?:use_react_native!\s*\(\s*)?:?new_arch_enabled\s*(?:=>|:)\s*(true|false)\b/.exec(
+          line,
+        )
+      if (argument) {
+        declarations.push({
+          source: 'ios/Podfile use_react_native! new_arch_enabled',
+          enabled: argument[1] === 'true',
+        })
+        continue
+      }
+      if (!/^\s*ENV\s*\[\s*['"]RCT_NEW_ARCH_ENABLED['"]\s*\]\s*(?:\|\|)?=/.test(line))
+        continue
+      // expo's generated conditional applies the parsed podfile property;
+      // it adds no independent renderer declaration.
+      if (
+        /^\s*ENV\s*\[\s*(['"])RCT_NEW_ARCH_ENABLED\1\s*\]\s*\|\|=\s*(['"])0\2\s+if\s+podfile_properties\s*\[\s*(['"])newArchEnabled\3\s*\]\s*==\s*(['"])false\4\s*;?\s*(?:#.*)?$/.test(
+          line,
+        )
+      )
+        continue
+      const match =
+        /^\s*ENV\s*\[\s*(['"])RCT_NEW_ARCH_ENABLED\1\s*\]\s*=\s*(['"])([01])\2\s*;?\s*(?:#.*)?$/.exec(
+          line,
+        )
+      if (!match)
+        throw new Error(
+          'ios/Podfile: RCT_NEW_ARCH_ENABLED must be an unconditional literal 0 or 1 assignment',
+        )
+      declarations.push({
+        source: 'ios/Podfile RCT_NEW_ARCH_ENABLED',
+        enabled: match[3] === '1',
+      })
+    }
+  } else {
+    const gradle = readProjectMetadata(join(dir, 'android/gradle.properties'), files)
+    if (gradle === null && files.exists(join(dir, 'android/gradle.properties')))
+      throw new Error('android/gradle.properties: unreadable native metadata')
+    for (const line of (gradle ?? '').split(/\r?\n/)) {
+      if (!/^\s*newArchEnabled\s*(?:[=:]|\s)/.test(line)) continue
+      const match = /^\s*newArchEnabled\s*[=:]\s*(true|false)\s*$/.exec(line)
+      if (!match)
+        throw new Error('android/gradle.properties: newArchEnabled must be true or false')
+      add(match[1], 'android/gradle.properties newArchEnabled', true)
+    }
+  }
+  const first = declarations[0]
+  if (!first) return undefined
+  if (declarations.some((entry) => entry.enabled !== first.enabled))
+    throw new Error(
+      `contradictory ${platform} native renderer metadata: ${declarations.map((entry) => entry.source).join(', ')}`,
+    )
+  return first.enabled ? 'fabric' : 'paper'
+}

package/cli/commands/detox.ts

@@ -18,7 +18,7 @@ import { dirname, resolve, join, relative } from 'path'
 import { rnxPublicBrand } from '../../src/public-brand'
 import { resolveCliAuth } from '../auth'
 import { registerRun, shouldRegisterRun } from '../run-registry'
-import { rnxExit } from '../run-rnx'
+import { peachExit } from '../run-rnx'
 import { buildShellUrl } from './control'
 import { discoverSootsimUrl } from './flow'
 import { resolveDefaultUploadOrigin } from './upload'
@@ -54,7 +54,7 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
 
   if (args.includes('--help') || args.includes('-h')) {
     console.log(HELP)
-    rnxExit(0)
+    peachExit(0)
   }
 
   if (args[0] === 'init') {
@@ -145,7 +145,7 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
       `  error: no detox tests found. expected one of: ${detoxDirs.join(', ')}\n` +
         `  run 'peach detox init' to scaffold a starter suite.`,
     )
-    rnxExit(1)
+    peachExit(1)
   }
   testDir ??= process.cwd()
 
@@ -162,7 +162,7 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
         `  error: ${rnxPublicBrand.commandName} detox runs Jest from this project, which needs its dev dependencies:\n` +
           `    npm i -D ${rnxPublicBrand.packageName} jest`,
       )
-      rnxExit(1)
+      peachExit(1)
     }
   }
 
@@ -378,7 +378,7 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
   ) {
     unlinkSync(resultsFile)
   }
-  rnxExit(code)
+  peachExit(code)
 }
 
 export type JestRunSummary = {
@@ -515,5 +515,5 @@ describe('example', () => {
   console.log(`\n  next:`)
   console.log(`    peach detox --app <dev-server-port>   # run the sample`)
   console.log(`    peach detox --watch`)
-  rnxExit(0)
+  peachExit(0)
 }

package/cli/commands/device.ts

@@ -6,7 +6,7 @@ import {
 } from 'peach-engine/settings/devices'
 import { DUO_REST_PROGRESS, type DuoFoldRest } from 'peach-engine/settings/duo-fold-bus'
 import { SOOTSIM_SHELL_COMMAND_NAME } from '../../src/menu'
-import { rnxExit } from '../run-rnx'
+import { peachExit } from '../run-rnx'
 import {
   callInBridge,
   createBridgeFromParsed,
@@ -121,7 +121,7 @@ async function readCurrentPosture(
 export async function runDeviceCommand(args: string[], opts: DeviceCommandOptions) {
   if (args.includes('--help') || args.includes('-h')) {
     usage()
-    rnxExit(0)
+    peachExit(0)
   }
 
   const subcommand = args[0]
@@ -130,7 +130,7 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
     const current = await readCurrentDevice(parsed)
     if (!current) {
       console.error('  error: could not read current device from the target sim')
-      rnxExit(1)
+      peachExit(1)
     }
     console.log(
       `  ${current.model}  ${current.width}x${current.height} pt  ${current.width * current.scale}x${current.height * current.scale} px  ${current.name}`,
@@ -148,12 +148,12 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
     const model = args[1]
     if (!model) {
       console.error('  error: device set expects a model')
-      rnxExit(1)
+      peachExit(1)
     }
     if (!(model in devices)) {
       console.error(`  error: unknown device "${model}"`)
       console.error('  run `peach device list` to see valid models')
-      rnxExit(1)
+      peachExit(1)
     }
     const parsed = parseBridgeCliArgs(args, { port: opts.port })
     const bridge = createBridgeFromParsed(parsed)
@@ -182,25 +182,25 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
     const want = raw === undefined || raw === 'toggle' || isDuoRest(raw) ? raw : null
     if (want === null) {
       console.error(`  error: device posture expects ${DUO_RESTS.join(', ')}, or toggle`)
-      rnxExit(1)
+      peachExit(1)
     }
     const current = await readCurrentPosture(parsed)
     if (!current) {
       console.error('  error: could not read current posture from the target sim')
-      rnxExit(1)
+      peachExit(1)
     }
     if (!devices[current.model].supportedPostures) {
       console.error(
         `  error: ${current.model} has a single posture — fold posture is only available on iphone-duo`,
       )
-      rnxExit(1)
+      peachExit(1)
     }
     if (!want) {
       if (!current.rest) {
         console.error(
           '  error: the Duo fold has no current rest; choose a posture explicitly',
         )
-        rnxExit(1)
+        peachExit(1)
       }
       console.log(`  ${current.rest} (${current.model})`)
       return
@@ -209,7 +209,7 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
       console.error(
         '  error: the Duo fold has no current rest; choose a posture explicitly',
       )
-      rnxExit(1)
+      peachExit(1)
     }
     const target: DuoFoldRest =
       want === 'toggle' ? (current.rest === 'closed' ? 'open' : 'closed') : want
@@ -246,7 +246,7 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
         console.error(
           `  error: the fold did not come to rest at ${target} within 10s (${current.model})`,
         )
-        rnxExit(1)
+        peachExit(1)
       }
       console.log(`  set posture: ${target} (${current.model})`)
     } finally {
@@ -257,5 +257,5 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
 
   usage()
   console.error(`  unknown subcommand: ${subcommand}`)
-  rnxExit(1)
+  peachExit(1)
 }

package/cli/commands/electron.ts

@@ -1,14 +1,14 @@
-// peach desktop — launch the installed desktop companion via the
-// electron driver, or the native host via the desktop driver with --native
-// (or PEACH_DESKTOP_APP). the drivers wrap findDesktopCompanion +
-// launchDesktopCompanion, so this command is a thin CLI surface that
-// parses options, prompts for install, and delegates everything else.
+// desktop launches the native host on Mac and Linux, and Electron on Windows.
 
 import { ensureProfile } from '../../src/profiles'
-import { findDesktopCompanion, wantsNativeDesktop } from '../desktop-companion'
+import {
+  findDesktopCompanion,
+  wantsNativeDesktop,
+  notifyDesktopMigration,
+} from '../desktop-companion'
 import { desktopDriver, electronDriver } from '../drivers'
 import { confirm } from '../prompt'
-import { rnxExit } from '../run-rnx'
+import { peachExit } from '../run-rnx'
 import { buildShellUrl } from './control'
 import { printMissingCompanionHint } from './no-bridge-hint'
 
@@ -24,7 +24,7 @@ function parseInlinePort(args: string[]): number | undefined {
   const port = raw ? Number(raw) : Number.NaN
   if (!Number.isInteger(port) || port <= 0) {
     console.error(`  invalid --port value: ${raw || '(missing)'}`)
-    rnxExit(1)
+    peachExit(1)
   }
   return port
 }
@@ -33,6 +33,8 @@ export async function resolveElectronLaunchUrl(
   args: string[],
   opts: ElectronOptions,
 ): Promise<string | undefined> {
+  const deepLink = args.find((arg) => arg.startsWith('peach://'))
+  if (deepLink) return new URL(deepLink).href
   const targetPort = parseInlinePort(args) ?? opts.port
   return targetPort ? buildShellUrl(String(targetPort)) : undefined
 }
@@ -49,6 +51,7 @@ options:
   --port <number>     connect to running dev server on this port
   --profile <id>      launch with an isolated persistent storage profile
   --ephemeral         launch with a temporary isolated storage profile
+  --electron          launch Electron on Windows; native app on Mac and Linux
   --native            launch the native desktop host (peach desktop install --native)
 
 examples:
@@ -57,17 +60,32 @@ examples:
   peach desktop --profile qa
   peach desktop --native
 `)
-    rnxExit(0)
+    peachExit(0)
   }
 
   const profileArg = args.find((_, i) => args[i - 1] === '--profile')
   const ephemeralProfile = args.includes('--ephemeral')
   if (profileArg && ephemeralProfile) {
     console.error('  peach desktop: --profile cannot be combined with --ephemeral')
-    rnxExit(1)
+    peachExit(1)
   }
   const profileId = profileArg ? ensureProfile(profileArg).id : undefined
-  const native = wantsNativeDesktop({ native: args.includes('--native') })
+  if (args.includes('--native') && args.includes('--electron')) {
+    console.error('  --native cannot be combined with --electron')
+    peachExit(1)
+  }
+  const native = wantsNativeDesktop({
+    native: args.includes('--electron')
+      ? false
+      : args.includes('--native')
+        ? true
+        : undefined,
+  })
+  notifyDesktopMigration()
+  if (args.includes('--electron') && native)
+    console.error(
+      '  Electron is Windows-only; using the native desktop app (peach install-desktop).',
+    )
   let install = findDesktopCompanion({ native })
   if (!install) {
     printMissingCompanionHint(native)
@@ -76,10 +94,10 @@ examples:
     if (canPrompt && (await confirm('run peach desktop install now?', true))) {
       console.log()
       const { runInstallDesktop } = await import('./install-desktop')
-      await runInstallDesktop(native ? ['--yes', '--native'] : ['--yes'])
+      await runInstallDesktop(['--yes'])
       install = findDesktopCompanion({ native })
     }
-    if (!install) rnxExit(1)
+    if (!install) peachExit(1)
   }
   console.log(`  launching ${install.path}`)
 
@@ -92,7 +110,7 @@ examples:
   })
   if (!result.launched) {
     console.error(`  ${result.message}`)
-    rnxExit(1)
+    peachExit(1)
   }
   console.log(`  ${result.message}`)
 }

package/cli/commands/flow.ts

@@ -7,7 +7,6 @@ import { tmpdir } from 'os'
 import * as path from 'path'
 import { scanDevServers } from '../../scripts/dev-server-scanner'
 import { loadOptionalDemoApps } from '../../scripts/optional-demo-registry'
-import { applyPeachConfigToUrl, type PeachConfig } from '../../src/config'
 import { printBridgeFailureDiagnostics } from '../bridge-diagnostics'
 import {
   SootSimBridgeFlowRunner,
@@ -15,14 +14,14 @@ import {
   type SootSimFlowProfileResult,
   type SootSimFlowTraceStep,
 } from '../bridge-flow-runner'
-import { readCurrentSimId, saveCurrentSimId } from '../current-sim'
-import { findDesktopCompanion } from '../desktop-companion'
+import { clearCurrentSimId, readCurrentSimId, saveCurrentSimId } from '../current-sim'
+import { findDesktopCompanion, notifyDesktopMigration } from '../desktop-companion'
 import { exportFlowSession } from '../flow-export'
 import { parseFlowFile, validateFlowFile } from '../flow-file'
 import { FlowLiveStatusReporter } from '../flow-live-status'
 import { finalizeFlowSession, keepFlowCandidate, startFlowSession } from '../flow-session'
 import { GLOBAL_FLAG_TAKES_VALUE } from '../parse-args'
-import { PeachExit, rnxExit } from '../run-rnx'
+import { PeachExit, peachExit } from '../run-rnx'
 import {
   BRIDGE_VALUE_FLAGS,
   createBridge,
@@ -32,15 +31,10 @@ import {
   parseBridgeCliArgs,
   resolveBridgePortForPin,
 } from '../ws-bridge'
-import {
-  buildShellUrl,
-  closeSimsBulk,
-  resolveShellBaseUrlForBridgePort,
-  runOpenCommand,
-  terminatePlaywrightHostsForSims,
-} from './control'
+import { closeSimsBulk, runOpenCommand, terminatePlaywrightHostsForSims } from './control'
 import { printShellPerfReport } from './inspect'
 import { resolveDefaultUploadOrigin } from './upload'
+import type { PeachConfig } from '../../src/config'
 import type { UploadResult } from './upload'
 
 export { parseFlowFile, validateFlowFile } from '../flow-file'
@@ -59,6 +53,7 @@ const FLOW_BOOLEAN_FLAGS = [
   '--headless',
   '--headed',
   '--proof',
+  '--load-env',
   '--no-shell',
   '--shell-only',
   '--dry-run',
@@ -207,9 +202,9 @@ export async function resolveAppFrontmatterTarget(
 export async function discoverSootsimUrl(): Promise<string | null> {
   const servers = await scanDevServers()
   const patched = servers.find((s) => s.patched)
-  if (patched) return `http://localhost:${patched.port}/__soot/`
+  if (patched) return `http://localhost:${patched.port}/__peachsim/`
   const any = servers[0]
-  if (any) return `http://localhost:${any.port}/__soot/`
+  if (any) return `http://localhost:${any.port}/__peachsim/`
   return null
 }
 
@@ -221,6 +216,9 @@ export async function runFlowPlayback(
   hooks: {
     beforeSteps?: () => Promise<void>
     runSteps?: (driver: SootSimBridgeFlowRunner, steps: MaestroStep[]) => Promise<void>
+    // afterSteps runs once the steps end, passed or failed, while the app is
+    // still on screen (maestro compare reads the app console here).
+    afterSteps?: (driver: SootSimBridgeFlowRunner) => Promise<void>
   } = {},
 ): Promise<number> {
   lastPreviewUploadResult = null
@@ -281,6 +279,8 @@ options:
                        frames without this, so its screenshot fails after 12
                        tries. use it for any run whose screenshots get
                        compared to anything
+  --load-env           load local app environment through open for
+                       react-native-config
   --electron           prefer opening the target in the desktop companion
   --sim <id>           target a specific current sim
   --validate           replay the drafted flow before clearing it
@@ -325,7 +325,7 @@ flow extension:
     path: marketing/hero
     withFrame: true
 `)
-    rnxExit(0)
+    peachExit(0)
   }
 
   const unexpected = findUnexpectedFlowArgs(args)
@@ -334,13 +334,13 @@ flow extension:
       console.error(`  error: ${problem.message}`)
     }
     console.error('\n  run `peach maestro --help` for the flags this command accepts')
-    rnxExit(1)
+    peachExit(1)
   }
 
   const flowPath = args[0]
   if (!fs.existsSync(flowPath)) {
     console.error(`  error: ${flowPath} not found`)
-    rnxExit(1)
+    peachExit(1)
   }
 
   const getFlag = (name: string) => args.find((_, i) => args[i - 1] === name)
@@ -408,7 +408,7 @@ flow extension:
     : ''
   if (previewBillingKind && previewBillingKind !== 'test_run') {
     console.error(`  error: invalid --billing-kind: ${previewBillingKind}`)
-    rnxExit(1)
+    peachExit(1)
   }
   const replaceArgs = args.flatMap((arg, index) =>
     args[index - 1] === '--replace' ? ['--replace', arg] : [],
@@ -439,7 +439,7 @@ flow extension:
   const { frontmatter, steps } = parseFlowFile(flowContent)
   if (steps.length === 0) {
     console.error('  error: flow file must contain a YAML array of steps')
-    rnxExit(1)
+    peachExit(1)
   }
   const targetDevice = deviceOverride || frontmatter.device || ''
   const targetTheme = themeOverride || frontmatter.theme || ''
@@ -474,16 +474,17 @@ flow extension:
     })
     if (pinned.error !== undefined) {
       console.error(`  error: ${pinned.error}`)
-      rnxExit(1)
+      peachExit(1)
     } else {
       parsedBridgeArgs.wsPort = pinned.port
     }
   }
-  if (wantElectron && !findDesktopCompanion()) {
+  if (wantElectron) notifyDesktopMigration()
+  if (wantElectron && !findDesktopCompanion({ native: false })) {
     console.error(
-      '  error: desktop companion not found. install or build it first with `bun run build:electron`',
+      '  error: desktop app not found. install it with `peach install-desktop`',
     )
-    rnxExit(1)
+    peachExit(1)
   }
 
   const effectiveOpenInNewSim =
@@ -551,26 +552,15 @@ flow extension:
     const discovered = await discoverSootsimUrl()
     if (!discovered) {
       console.error('  error: no current sim and no peach target found')
-      rnxExit(1)
+      peachExit(1)
     }
     openTarget = discovered
   }
 
-  if (openTarget && targetDevice) {
-    const shellBaseUrl = applyPeachConfigToUrl(
-      pinnedShellBaseUrl || resolveShellBaseUrlForBridgePort(parsedBridgeArgs.wsPort),
-      targetAppResolution.runtimeConfig,
-    )
-    const url = new URL(
-      await buildShellUrl(openTarget, shellBaseUrl, { proof: proofMode }),
-    )
-    url.searchParams.set('device', targetDevice)
-    openTarget = url.toString()
-  }
-
   if (openTarget) {
     const openArgs = [openTarget]
     if (pinnedShellBaseUrl) openArgs.push('--base-url', pinnedShellBaseUrl)
+    if (targetDevice) openArgs.push('--device', targetDevice)
     openArgs.push(...replaceArgs)
     openArgs.push(...remapArgs)
     if (effectiveOpenInNewSim) {
@@ -587,6 +577,7 @@ flow extension:
       openArgs.push('--headless')
     }
     if (proofMode) openArgs.push('--proof')
+    if (args.includes('--load-env')) openArgs.push('--load-env')
     const opened = await runOpenCommand(openArgs, {
       port: parsedBridgeArgs.wsPort,
       timeoutMs: parsedBridgeArgs.commandTimeoutMs,
@@ -714,6 +705,16 @@ flow extension:
   let exitCode = 0
   const dryRun = args.includes('--dry-run') || args.includes('--no-run')
   const startsWithLaunchApp = !!steps[0]?.launchApp
+  let afterStepsRan = false
+  const runAfterSteps = async () => {
+    if (!hooks.afterSteps || afterStepsRan) return
+    afterStepsRan = true
+    try {
+      await hooks.afterSteps(driver)
+    } catch (hookErr: any) {
+      console.warn(`  after-steps hook failed: ${hookErr?.message || String(hookErr)}`)
+    }
+  }
   try {
     if (!startsWithLaunchApp) {
       await driver.waitForTree(120000)
@@ -788,6 +789,7 @@ flow extension:
     await hooks.beforeSteps?.()
     if (hooks.runSteps) await hooks.runSteps(driver, steps)
     else await driver.runFlow(steps, { skipPlan: dryRun })
+    await runAfterSteps()
     if (profile) {
       profileResult = await driver.stopProfile()
     }
@@ -828,6 +830,7 @@ flow extension:
     }
     console.log()
   } catch (err: any) {
+    await runAfterSteps()
     if (profile && !profileResult) {
       try {
         profileResult = await driver.stopProfile()
@@ -1068,9 +1071,14 @@ async function closeFlowOwnedSims(
     const openIds = ids.filter((id) =>
       sims.some((sim) => sim.id === id && sim.readyState === 'open'),
     )
-    if (openIds.length === 0) return
     const result = await closeSimsBulk(bridge, wsPort, commandTimeoutMs, openIds)
     await terminatePlaywrightHostsForSims(sims, openIds)
+    // retiring a flow-owned browser also retires its selection. a caller that
+    // selected another sim during the flow keeps that selection.
+    const selected = readCurrentSimId()
+    if (selected && ids.includes(selected) && !result.remaining.includes(selected)) {
+      clearCurrentSimId()
+    }
     if (result.closed.length > 0) {
       console.log(`  closed flow sim(s): ${result.closed.join(', ')}`)
     }
@@ -1185,7 +1193,7 @@ async function runFlowSession(args: string[]) {
       const result = keepFlowCandidate()
       if (!result.active) {
         console.error('  no active flow draft — run `peach maestro start` first')
-        rnxExit(1)
+        peachExit(1)
       }
       if (!result.kept) {
         console.log('  no pending action to keep')
@@ -1214,7 +1222,7 @@ async function runFlowSession(args: string[]) {
       )
       if (!result.active) {
         console.error('  no active flow draft — run `peach maestro start` first')
-        rnxExit(1)
+        peachExit(1)
       }
       if (!result.valid) {
         console.error('  flow draft is not valid:')
@@ -1222,7 +1230,7 @@ async function runFlowSession(args: string[]) {
         console.error(
           '  draft preserved — keep at least one real interaction or run `peach maestro start` to reset',
         )
-        rnxExit(1)
+        peachExit(1)
       }
 
       if (validate) {
@@ -1267,13 +1275,13 @@ async function runFlowSession(args: string[]) {
       const flowPath = args[1]
       if (!flowPath || flowPath.startsWith('-')) {
         console.error('  usage: peach maestro validate <path>')
-        rnxExit(1)
+        peachExit(1)
       }
       const issues = validateFlowFile(flowPath)
       if (issues.length > 0) {
         console.error(`  x ${flowPath} failed validation:`)
         for (const issue of issues) console.error(`    - ${issue}`)
-        rnxExit(1)
+        peachExit(1)
       }
       console.log(`  + ${flowPath} looks valid`)
       return

package/cli/commands/guest-host.ts

@@ -1,10 +1,48 @@
 // what `peach swift` and `peach kotlin` share: a loopback-only guest host
 // and the teardown of the simulator, driver and bridge their open started.
 import { isLoopbackHost } from '../../src/backend-origin'
+import { clearCurrentSimId, readCurrentSimId } from '../current-sim'
 import { createBridge } from '../ws-bridge'
-import { runCloseCommand, type OpenCommandResources } from './control'
+import {
+  printDriverDiagnosticLogTail,
+  runCloseCommand,
+  type OpenCommandResources,
+} from './control'
 import type http from 'node:http'
 
+export async function waitForGuestCompletion(
+  resources: OpenCommandResources,
+  signal: AbortSignal,
+  label: string,
+): Promise<number> {
+  if (signal.aborted) return 0
+  let onAbort: () => void = () => {}
+  const aborted = new Promise<null>((resolve) => {
+    onAbort = () => resolve(null)
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+  try {
+    const result = await Promise.race([
+      aborted,
+      ...(resources.driver?.completion ? [resources.driver.completion] : []),
+    ])
+    if (result === null) return 0
+    // an exited driver has already closed its page and simulator.
+    if (result.signal === null && result.code !== null) {
+      if (resources.simId && readCurrentSimId() === resources.simId) clearCurrentSimId()
+      delete resources.simId
+    }
+    const code = result.code === 0 && result.signal === null ? 0 : 1
+    if (code && resources.driver) printDriverDiagnosticLogTail(resources.driver)
+    console.log(
+      `  ${label} completed: ${result.signal ? `signal ${result.signal}` : `exit ${result.code ?? 'unknown'}`}${result.code !== null && resources.driver?.completionFile ? `; receipt ${resources.driver.completionFile}` : ''}`,
+    )
+    return code
+  } finally {
+    signal.removeEventListener('abort', onAbort)
+  }
+}
+
 export function isLoopbackGuestRequest(
   req: http.IncomingMessage,
   origin: string,