peachsim 0.1.626 → 0.1.628

package/cli/commands/inspect.ts

@@ -17,6 +17,7 @@ import { getCliIdentityKey } from '../current-sim'
 import { rememberFlowCandidate } from '../flow-session'
 import { maybeHint } from '../hints'
 import { shouldPrintInspectNotice } from '../inspect-notice-state'
+import { levenshtein } from '../levenshtein'
 import { TOP_LEVEL_RUNTIME_COMMANDS } from '../parse-args'
 import { rethrowIfExit, rnxExit } from '../run-rnx'
 import {
@@ -243,34 +244,6 @@ function scoreIdSimilarity(needle: string, candidate: string): number {
   return levenshtein(needle, candidate) - prefix
 }
 
-function levenshtein(a: string, b: string): number {
-  if (a === b) return 0
-  if (!a.length) return b.length
-  if (!b.length) return a.length
-  // standard two-row dp: prev[] is the previous row, cur[] is the row being
-  // computed; swap pointers per outer iteration. the earlier in-place rolling
-  // version overwrote prev[j-1] twice per cell and never set prev[0]=i, so
-  // distance(`kitten`,`sitting`) returned 8 instead of 3 and the fuzzy-suggest
-  // ranking was effectively random.
-  let prev = new Array<number>(b.length + 1)
-  let cur = new Array<number>(b.length + 1)
-  for (let j = 0; j <= b.length; j++) prev[j] = j
-  for (let i = 1; i <= a.length; i++) {
-    cur[0] = i
-    for (let j = 1; j <= b.length; j++) {
-      cur[j] = Math.min(
-        prev[j] + 1,
-        cur[j - 1] + 1,
-        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
-      )
-    }
-    const tmp = prev
-    prev = cur
-    cur = tmp
-  }
-  return prev[b.length]
-}
-
 function formatNetworkStatus(e: NetworkEntryPayload): string {
   if (e.error) return 'err'
   if (e.status == null) return ' … '
@@ -3539,7 +3512,16 @@ export async function runInspect(args: string[], opts: InspectOptions) {
           if (reloadResult && reloadResult.engineStale) {
             console.log('  engine build changed since page load — full page reload')
           }
-        } catch {
+        } catch (error) {
+          // no sim at all is not a reload in flight: report it rather than
+          // waiting out the reconnect budget.
+          const message = error instanceof Error ? error.message : String(error)
+          if (
+            message === 'no sim connected' ||
+            message.startsWith('could not connect to ws://')
+          ) {
+            throw error
+          }
           // the sim may already be in the middle of reloading; fall through to reconnect wait
         }
         console.log('  reloading...')
@@ -3623,7 +3605,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
             // ignore errors checking for errors
           }
         }
-        if (readyResult && !readyResult.ready) {
+        if (!readyResult?.ready) {
           rnxExit(1)
         }
         break
@@ -4655,15 +4637,18 @@ export async function runInspect(args: string[], opts: InspectOptions) {
     // single 15s timeout into ~60s of apparent hang (QA F19-1). there is
     // nothing useful to fetch from a sim that just timed out, so skip them.
     const timedOut = /^command timed out after (\d+)s$/.exec(message)
-    // a disconnected / never-connected bridge is genuinely gone; recover is
-    // right and probing it would just re-incur a full timeout.
+    // a disconnected bridge is genuinely gone; recover is right and probing
+    // it would just re-incur a full timeout. no bridge at all means there is
+    // no sim to recover, only one to open.
     const disconnected =
       message.startsWith('sim disconnected:') ||
-      message.startsWith('bridge never reconnected') ||
-      message.startsWith('could not connect to ws://')
+      message.startsWith('bridge never reconnected')
     if (unknownSim) {
       await printUnknownSimHint(bridge, wsPort, unknownSim[1])
-    } else if (/^no sim connected$/.test(message)) {
+    } else if (
+      /^no sim connected$/.test(message) ||
+      message.startsWith('could not connect to ws://')
+    ) {
       printMissingSimHint(wsPort)
     } else if (timedOut) {
       // a command timeout alone does not mean a wedged sim — a large screen
@@ -4677,9 +4662,9 @@ export async function runInspect(args: string[], opts: InspectOptions) {
         process.stderr.write(
           `  the sim is still responsive — '${cmd}' just exceeded the ${timedOut[1]}s command budget.\n` +
             `  the screen's node tree is large; narrow the query or raise the budget:\n` +
-            `    peach  --testid <id>     # scope to one subtree\n` +
+            `    peach ${cmd} --subtree <id>   # scope to one subtree\n` +
             `    peach find --testid <id>       # targeted single-node lookup\n` +
-            `    peach  --timeout 60000   # raise per-command budget (ms)\n`,
+            `    peach ${cmd} --timeout 60000  # raise per-command budget (ms)\n`,
         )
       } else {
         printRecoverHint()

package/cli/commands/maestro-generate.ts

@@ -4,6 +4,7 @@ import { mkdtempSync, writeFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import yaml from 'yaml'
+import { isRecord } from '../../src/is-record'
 import { authHeaderValue, resolveCliAuth } from '../auth'
 import { registerRun, stepSummaryFromTrace } from '../run-registry'
 import { createBridgeFromParsed, parseBridgeCliArgs } from '../ws-bridge'
@@ -18,7 +19,6 @@ import {
 } from './flow'
 import { inspectDescribe } from './inspect/core'
 import { resolveDefaultUploadOrigin } from './upload'
-import { isRecord } from '../../src/is-record'
 
 const DEFAULT_TEST_MODEL = process.env.PEACH_TEST_MODEL || 'deepseek-v4-flash'
 const DESCRIBE_CONTEXT_LIMIT = 18_000
@@ -239,14 +239,7 @@ export function buildFlowArgs(
   flowPath: string,
   origin: string,
 ) {
-  const out = [
-    flowPath,
-    '--preview',
-    '--preview-origin',
-    origin,
-    '--billing-kind',
-    'test_run',
-  ]
+  const out = [flowPath, '--preview', '--preview-origin', origin]
   for (let i = 0; i < args.length; i++) {
     if (i === promptIndex) continue
     const arg = args[i]
@@ -285,10 +278,10 @@ export function findUnexpectedGenerateArgs(
     if (i === promptIndex) continue
     const arg = args[i]
     if (!arg) continue
-    // generate writes --billing-kind onto the flow argv itself and getFlag
-    // takes the first occurrence, so a caller's value loses to it in silence.
+    // a generated flow's recording is an ordinary preview upload; the only
+    // billing kind is a hosted test job's, which the recorder sets.
     if (arg === '--billing-kind') {
-      problems.push({ arg, message: `${arg} is set by peach maestro generate` })
+      problems.push({ arg, message: `${arg} is only for hosted test jobs` })
       i += 1
       continue
     }

package/cli/commands/maestro.ts

@@ -26,6 +26,7 @@ import { RnxExit } from '../run-rnx'
 import {
   findUnexpectedFlowArgs,
   FLOW_ARG_VALUE_FLAGS,
+  getLastFlowPreviewUploadError,
   getLastFlowPreviewUploadResult,
   getLastFlowTraceSteps,
   hoistLeadingSimFlag,
@@ -728,6 +729,10 @@ export async function runMaestro(
     console.error(`  error: ${target} not found`)
     return 1
   }
+  // cwd is the real path, so name every flow from the target's real path too:
+  // a target under a symlink (macOS /tmp, /var/folders) otherwise reports as
+  // ../../../var/folders/... instead of flows/login.yaml.
+  target = fs.realpathSync(target)
 
   let files: string[]
   let workspaceConfig: MaestroWorkspaceConfig = {}
@@ -886,24 +891,29 @@ export async function runMaestro(
     // the upload failed, so the flow never disappears from the collected
     // entries.
     if (args.includes('--preview')) {
+      const uploaded = Boolean(upload?.shareId || upload?.previewUrl)
       const previewPayload = {
         flow: path.relative(cwd, file) || file,
         previewId: upload?.shareId ?? null,
         previewUrl: upload?.previewUrl ?? null,
-        // the failing step as the junit report names it, on one line
+        // the failing step as the junit report names it, on one line, else
+        // why the required recording upload failed
         failure:
-          exit === 0
+          exit === 0 && uploaded
             ? null
-            : failureFromTraceSteps(traceSteps, 'flow playback failed').body.split(
-                '\n',
-              )[0],
+            : failureFromTraceSteps(
+                traceSteps,
+                uploaded
+                  ? 'flow playback failed'
+                  : `recording upload failed: ${getLastFlowPreviewUploadError() ?? 'no preview returned'}`,
+              ).body.split('\n')[0],
       }
       try {
         for (const name of cloudTestResultFileNames('preview', flowIndex, files.length)) {
           fs.writeFileSync(path.join(cwd, name), JSON.stringify(previewPayload))
         }
       } catch {}
-      if (!upload?.shareId && !upload?.previewUrl) {
+      if (!uploaded) {
         console.error('  error: required hosted recording upload failed')
         if (exit === 0) exit = 1
         if (worstExit === 0) worstExit = 1

package/cli/commands/mode.ts

@@ -1,5 +1,6 @@
 import { rnxExit } from '../run-rnx'
 import { runScreenshotMode } from './screenshot-mode'
+import { runShowTouchesMode } from './show-touches-mode'
 import { runThreeMode } from './three-mode'
 
 interface ModeOptions {
@@ -8,7 +9,7 @@ interface ModeOptions {
 }
 
 const VALUE_FLAGS = new Set(['--sim', '--port', '-p'])
-const SUBCOMMANDS = new Set(['screenshot', 'three'])
+const SUBCOMMANDS = new Set(['screenshot', 'three', 'show-touches', 'touches'])
 
 function findSubcommand(args: string[]): { name: string; index: number } | null {
   for (let i = 0; i < args.length; i++) {
@@ -32,21 +33,20 @@ peach mode — toggle live display modes
 
 usage:
   peach mode screenshot [on|off|toggle]
+  peach mode show-touches [on|off|toggle]
   peach mode three [on|off|toggle]
   peach mode three configure [options]
 `)
 }
 
 export async function runMode(args: string[], opts: ModeOptions): Promise<void> {
-  if (args.includes('--help') || args.includes('-h')) {
-    printHelp()
-    return
-  }
-
   const sub = findSubcommand(args)
   if (!sub) {
     printHelp()
-    rnxExit(1)
+    if (!args.includes('--help') && !args.includes('-h')) {
+      rnxExit(1)
+    }
+    return
   }
 
   const rest = withoutSubcommand(args, sub.index)
@@ -54,5 +54,9 @@ export async function runMode(args: string[], opts: ModeOptions): Promise<void>
     await runScreenshotMode(rest, opts)
     return
   }
+  if (sub.name === 'show-touches' || sub.name === 'touches') {
+    await runShowTouchesMode(rest, opts)
+    return
+  }
   await runThreeMode(rest, opts)
 }

package/cli/commands/platform.ts

@@ -454,6 +454,7 @@ async function runRemoteBox(
   }
   const created = await box.createPrebuiltBundleBox({
     bundle: new Uint8Array(artifact.bytes),
+    device: selectedDevice,
     name: input.name ?? boxNameForBundle(input.bundlePath),
     endpoint,
     apiOrigin: box.cloudBoxApiOrigin(args, auth),

package/cli/commands/report-issue.ts

@@ -260,7 +260,7 @@ export async function runReportIssue(
       return 2
     }
     const approved = await dependencies.confirmSubmission(
-      'send this compatibility report to the peach team??',
+      'send this compatibility report to the peach team?',
       false,
     )
     if (!approved) {

package/cli/commands/setup.ts

@@ -54,6 +54,7 @@ interface SetupOptions {
 
 interface SetupRunOptions {
   launchConnectRN?: boolean
+  port?: number
 }
 
 export interface SetupResult {
@@ -120,6 +121,7 @@ export async function runSetup(
           channel: 'stable',
           setActive: true,
           protectVersions: activeRuntime ? [activeRuntime] : [],
+          quiet: !options.json,
         })
       const result = options.json
         ? await install()
@@ -130,10 +132,16 @@ export async function runSetup(
     let serviceInstalled = serviceStatus.installed
     if (service && !serviceStatus.installed && !options.dryRun) {
       if (options.json) {
-        await daemonInstall({ port: DEFAULT_SOOTSIM_BRIDGE_PORT, force: false })
+        await daemonInstall({
+          port: runOptions.port ?? DEFAULT_SOOTSIM_BRIDGE_PORT,
+          force: false,
+        })
       } else {
         console.log(`\n  ${accent('◆')} ${bold('Enabling the background service')}`)
-        await daemonInstall({ port: DEFAULT_SOOTSIM_BRIDGE_PORT, force: false })
+        await daemonInstall({
+          port: runOptions.port ?? DEFAULT_SOOTSIM_BRIDGE_PORT,
+          force: false,
+        })
       }
       serviceInstalled = true
     }
@@ -144,13 +152,10 @@ export async function runSetup(
 
     if (launchConnectRN) {
       console.log(`\n  ${accent('◆')} Opening ConnectRN`)
-      await runOpenCommand([
-        'ConnectRN',
-        '--driver',
-        simulatorDriver,
-        '--no-describe',
-        '--quiet',
-      ])
+      await runOpenCommand(
+        ['ConnectRN', '--driver', simulatorDriver, '--no-describe', '--quiet'],
+        { port: runOptions.port },
+      )
     }
 
     const productAnalytics = await decidePrivacy(options, privacy)
@@ -324,7 +329,7 @@ async function decideSimulatorDriver(
     desktopDescription,
     'The Desktop app opens in a dedicated native window.',
   ])
-  const choice = await select('Where should peach open??', [
+  const choice = await select('Where should peach open?', [
     'Browser (recommended)  No additional download',
     desktopChoice,
   ])
@@ -343,7 +348,7 @@ async function decidePrivacy(
     'Reports can contain package compatibility or an error class.',
     'They never contain your code or app data.',
   ])
-  return confirm('Share bounded diagnostics to improve peach??', false)
+  return confirm('Share bounded diagnostics to improve peach?', false)
 }
 
 async function decideRepository(

package/cli/commands/show-touches-mode.ts

@@ -0,0 +1,33 @@
+// peach mode show-touches — toggle OS touch indicators (Show Single Touches / Show taps)
+// in the running peach sim.
+
+import { rnxExit } from '../run-rnx'
+import { runShellBooleanMode, type ShellBooleanModeOptions } from './shell-boolean-mode'
+
+export async function runShowTouchesMode(args: string[], opts: ShellBooleanModeOptions) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+peach mode show-touches — toggle touch indicator overlays
+
+usage:
+  peach mode show-touches [on|off|toggle]
+
+arguments:
+  on        enable touch indicators
+  off       disable touch indicators
+  toggle    flip the current state (default)
+
+examples:
+  peach mode show-touches
+  peach mode show-touches on
+  peach mode show-touches off
+`)
+    rnxExit(0)
+  }
+
+  await runShellBooleanMode(args, opts, {
+    modeKey: 'showTouches',
+    displayName: 'show-touches',
+    actionId: 'toggle-touches',
+  })
+}

package/cli/commands/skills.ts

@@ -9,10 +9,26 @@ import * as fs from 'fs'
 import * as os from 'os'
 import * as path from 'path'
 import { fileURLToPath } from 'url'
+import { getCliVersion } from '../../src/cli-version'
+import { rnxHomeDir } from '../../src/home-paths'
 import { rnxPublicBrand } from '../../src/public-brand'
 import { rnxExit } from '../run-rnx'
 
+declare const __PEACH_BUNDLED_SKILLS__: Record<string, string>
+
 function getSkillsDir(): string {
+  // the standalone binary carries its skills instead of a package directory;
+  // write them once per cli version so installs can link to real files.
+  if (typeof __PEACH_BUNDLED_SKILLS__ !== 'undefined') {
+    const dir = path.join(rnxHomeDir(), 'skills', getCliVersion())
+    for (const [file, body] of Object.entries(__PEACH_BUNDLED_SKILLS__)) {
+      const target = path.join(dir, file)
+      if (fs.existsSync(target)) continue
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.writeFileSync(target, body)
+    }
+    return dir
+  }
   try {
     const pkgPath = fileURLToPath(
       import.meta.resolve(`${rnxPublicBrand.packageName}/package.json`),

package/cli/commands/test.ts

@@ -873,6 +873,20 @@ export async function runCloudTest(
 
     const { id } = (await response.json()) as { id: string }
     console.log(`  cloud test job submitted: ${id}`)
+    // a job whose app this process serves over its tunnel cannot finish once
+    // the process exits, so an interrupt cancels it rather than leaving it to
+    // fail flow by flow while it bills.
+    if (closeTunnel) {
+      const cancelOnSignal = () => {
+        console.error(`\n  interrupted: cancelling ${id}`)
+        void cancelCloudTest(id, origin).finally(() => {
+          closeTunnel?.()
+          process.exit(130)
+        })
+      }
+      process.once('SIGINT', cancelOnSignal)
+      process.once('SIGTERM', cancelOnSignal)
+    }
 
     const pollUrl = `${origin.replace(/\/$/, '')}/api/sootsim/runner/jobs?id=${encodeURIComponent(id)}`
     const startedAt = Date.now()
@@ -970,7 +984,14 @@ export async function runTest(
     return runCloudTest(args, opts)
   }
 
-  const selected = resolveTestCommand(args)
+  // a missing or unknown target is the caller's mistake: one line, no stack.
+  let selected: ReturnType<typeof resolveTestCommand>
+  try {
+    selected = resolveTestCommand(args)
+  } catch (error) {
+    console.error(`  error: ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
   const app = appFromArgs(args)
   const appTarget = app
     ? await resolveTestAppTarget(app)

package/cli/commands/upload.ts

@@ -194,7 +194,8 @@ options:
   --repo <repo>      repo name for --owner; the signed-in user must belong
                      to the local/org team that owns the link
   --billing-kind test_run
-                     meter this upload as a natural-language test run
+                     the recording of a hosted test job, covered by the
+                     job's minutes (set by the hosted recorder)
   --sim <sim>        target a specific sim (see: peach list)
   --open             open the resulting /preview/<id> url in the browser
   --assets-only      drop API/JSON/HTML records before upload; keep images,
@@ -476,6 +477,12 @@ export async function runUpload(
     console.error(`  invalid --billing-kind: ${billingKind}`)
     rnxExit(1)
   }
+  // the hosted recorder names the job whose minutes cover this recording
+  const runnerJobId = process.env.CONTRAST_RUNNER_JOB_ID
+  if (billingKind === 'test_run' && !runnerJobId) {
+    console.error('  --billing-kind test_run is only for hosted test jobs')
+    rnxExit(1)
+  }
   if (!eventsPath && !videoPath) {
     console.error(
       '  preview uploads require playback data: pass --events or --video.\n' +
@@ -1045,6 +1052,7 @@ export async function runUpload(
     pullRequestNumber: provenance.pullRequestNumber ?? undefined,
     pullRequestTitle: provenance.pullRequestTitle ?? undefined,
     billingKind: billingKind === 'test_run' ? 'test_run' : undefined,
+    runnerJobId: billingKind === 'test_run' ? runnerJobId : undefined,
     runScope: runScope || undefined,
     files: prepared.map((f) => ({
       url: f.url,
@@ -1161,19 +1169,21 @@ export async function runUpload(
     if (e.phase === 'init' && e.status === 401) {
       console.error('  preview upload requires a valid login.')
       console.error('  run `peach login` and retry.')
-      rnxExit(1)
+      rnxExit(1, 'preview upload requires a valid login')
     }
     if (e.status === 402) {
       // billing gate — surface the server's own `message`, not raw JSON.
-      console.error(
-        `  ${parseServerMessage(e.responseText) ?? 'preview uploads require Personal, Team, or an active trial — upgrade from the billing dialog.'}`,
-      )
-      rnxExit(1)
+      const message =
+        parseServerMessage(e.responseText) ??
+        'preview uploads require Personal, Team, or an active trial — upgrade from the billing dialog.'
+      console.error(`  ${message}`)
+      rnxExit(1, message)
     }
     // PresignedUploadError.message already carries the "<phase> failed:"
     // prefix — don't re-prefix it (that produced "init failed: init failed:").
-    console.error(`  ${e.message ?? `${e.phase ?? 'upload'} failed: ${String(err)}`}`)
-    rnxExit(1)
+    const message = e.message ?? `${e.phase ?? 'upload'} failed: ${String(err)}`
+    console.error(`  ${message}`)
+    rnxExit(1, message)
   }
 
   const previewUrl = `${publicOrigin}${finalize.url}`

package/cli/commands/welcome.ts

@@ -4,14 +4,14 @@ import { printBrand } from '../ui'
 import { runOpenCommand } from './control'
 import { runSetup } from './setup'
 
-export async function runWelcome(): Promise<number> {
+export async function runWelcome(port: number | undefined): Promise<number> {
   if (!isOnboardingComplete() && canPromptForPrivacyChoice()) {
-    await runSetup([], { launchConnectRN: true })
+    await runSetup([], { launchConnectRN: true, port })
     return 0
   }
 
   printBrand('Run any React Native app in a local simulator.')
   console.log(`\n  Opening ConnectRN`)
-  await runOpenCommand(['ConnectRN', '--no-describe', '--quiet'])
+  await runOpenCommand(['ConnectRN', '--no-describe', '--quiet'], { port })
   return 0
 }

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

@@ -7,8 +7,10 @@ import { createBrowserPointerDispatcher } from '../../../peach-engine/src/render
 //
 // it resolves playwright from the absolute path the driver hands it, launches
 // Chrome for Testing, opens the target url, then keeps itself (and therefore
-// the browser) alive until the browser disconnects. all inputs arrive through
-// the environment.
+// the browser) alive until the page asks it to close (`peach close`, or the
+// bridge reaping the sim after AUTOMATION_SIM_IDLE_REAP_TTL_MS with no cli),
+// the browser disconnects, or its owning session exits. all inputs arrive
+// through the environment.
 //
 // it stays a source string rather than a module of its own: playwright is
 // resolved from the user's project at runtime and is not a dependency here, so
@@ -444,16 +446,17 @@ const cleanupProfile = () => {
     const request = readBrowserCompositeCaptureRequest(value);
     const session = await source.page.context().newCDPSession(source.page);
     try {
+      const { clip, originX, originY } = resolveBrowserCompositeCdpClip(
+        request,
+        await session.send('Page.getLayoutMetrics'),
+      );
       const result = await session.send('Page.captureScreenshot', {
         format: 'png',
         fromSurface: true,
         captureBeyondViewport: true,
-        clip: resolveBrowserCompositeCdpClip(
-          request,
-          await session.send('Page.getLayoutMetrics'),
-        ),
+        clip,
       });
-      return 'data:image/png;base64,' + result.data;
+      return { dataUrl: 'data:image/png;base64,' + result.data, originX, originY };
     } finally {
       await session.detach();
     }
@@ -515,7 +518,12 @@ const cleanupProfile = () => {
       process.stderr.write('[console.error] ' + m.text() + '\\n');
     }
   });
-  page.on('crash', () => process.stderr.write('[page] renderer crashed\\n'));
+  // a crashed renderer never runs the page's bridge close path, so nothing
+  // would ever close this host.
+  page.on('crash', () => {
+    process.stderr.write('[page] renderer crashed; closing playwright host\\n');
+    void shutdown(1);
+  });
   try {
     await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
   } catch (err) {

package/cli/drivers/playwright.ts

@@ -16,6 +16,7 @@ import { spawn } from 'child_process'
 import { closeSync, mkdtempSync, openSync, readFileSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
+import { AUTOMATION_SIM_IDLE_REAP_TTL_MS } from '../../src/bridge-constants'
 import { playwrightHostLogName } from '../../src/playwright-host-log'
 import { ensureProfile, playwrightProfileUserDataDir } from '../../src/profiles'
 import { RNX_INTERNAL_CHILDREN, RNX_INTERNAL_COMMAND } from '../internal-child'
@@ -172,12 +173,14 @@ async function launch(opts: DriverLaunchOptions): Promise<DriverLaunchResult> {
         }${hint ? `\n${hint}` : ''}`,
       }
     }
-    // name the lifetime tie: the host watchdog closes chrome ~5s after the
-    // owning session pid exits, which surprises one-shot/detached shells
-    // (their topmost non-init ancestor is the shell itself, so the sim dies
-    // the moment the command finishes).
+    // name both lifetime bounds: the bridge closes an automation sim no cli
+    // has touched for the idle window, and the host watchdog closes chrome ~5s
+    // after the owning session pid exits, which surprises one-shot/detached
+    // shells (their topmost non-init ancestor is the shell itself, so the sim
+    // dies the moment the command finishes).
     const ownerComm = getProcessComm(ownerPid)
-    const ownerNote = ` — browser closes when pid ${ownerPid}${ownerComm ? ` (${ownerComm})` : ''} exits`
+    const idleMinutes = AUTOMATION_SIM_IDLE_REAP_TTL_MS / 60_000
+    const ownerNote = ` — browser closes after ${idleMinutes} min with no peach command, or when pid ${ownerPid}${ownerComm ? ` (${ownerComm})` : ''} exits`
     return {
       launched: true,
       message: `playwright chrome launched → ${opts.url}${ownerNote}`,

package/cli/help-core.ts

@@ -96,8 +96,13 @@ Run \`peach <command> --help\` for leaf availability and usage.`
 export function renderRnxHelp(options: RnxHelpOptions): string {
   const command = options.command ?? null
   const commandArgs = options.commandArgs ?? []
+  // the preview selectors and backend lists describe the factory's browser
+  // backend; the public cli runs the node backend and never sees them.
+  const factory = options.backend === 'browser'
   if (!command) {
-    return `${renderCliIndexHelp(HELP_CONTEXT, formatFlagHelp()).trimEnd()}
+    const index = renderCliIndexHelp(HELP_CONTEXT, formatFlagHelp()).trimEnd()
+    if (!factory) return index
+    return `${index}
 
 browser preview selectors:
   peach web                     select the existing Factory web preview
@@ -108,7 +113,7 @@ ${renderRootAvailability(options.backend)}`
   }
 
   let body: string | null
-  if (command === 'web' || command === 'ios' || command === 'android') {
+  if (factory && (command === 'web' || command === 'ios' || command === 'android')) {
     body = renderPreviewHelp(command)
   } else if (options.group === command && !options.prefer) {
     body = renderCliGroupHelp(command, HELP_CONTEXT, formatFlagHelp())
@@ -130,11 +135,11 @@ ${renderRootAvailability(options.backend)}`
   const registration = getRnxCommandRegistration(command)
   if (!registration) return body
   const current = getRnxCommandAvailability(command, commandArgs, options.backend)
+  if (!factory && current.available) return body
   const currentLine = current.available
     ? `${options.backend} backend: available`
     : `${options.backend} backend: ${current.reason}`
-  const factoryLeaves =
-    options.backend === 'browser' ? renderFactoryBrowserLeaves(command) : null
+  const factoryLeaves = factory ? renderFactoryBrowserLeaves(command) : null
   return `${body.trimEnd()}
 
 ${factoryLeaves ? `${factoryLeaves}\n\n` : ''}${backendLabel(command, commandArgs)}