peachsim 0.1.578 → 0.1.580

package/cli/commands/login.ts

@@ -8,6 +8,7 @@ import {
   writeSharedDesktopAuthSession,
   type SharedDesktopAuthSession,
 } from '../../src/auth/shared-session'
+import { isLoopbackHost } from '../../src/backend-origin'
 import { rnxPublicBrand } from '../../src/public-brand'
 import { rnxExit } from '../run-rnx'
 
@@ -176,11 +177,8 @@ async function runDevLogin(origin: string): Promise<LoginResult> {
 function isLocalOrigin(origin: string): boolean {
   try {
     const hostname = new URL(origin).hostname.replace(/^\[|\]$/g, '').toLowerCase()
-    if (hostname === 'localhost') return true
-    if (/^127(?:\.\d{1,3}){3}$/.test(hostname)) return true
-    if (hostname === '::1' || hostname === '0.0.0.0') return true
+    if (isLoopbackHost(hostname)) return true
     if (hostname.endsWith('.local')) return true
-    if (hostname.endsWith('.localhost')) return true
     // VM↔host bridge aliases — orb, docker, lima, multipass all forward the
     // host on a well-known name (IPv4 or IPv6) so a VM-internal `peach login`
     // can still take the dev-login fast path against the host's Contrast dev
@@ -321,7 +319,7 @@ export async function runLogin(args: string[]) {
         return
       }
 
-      const url = new URL(`${origin.replace(/\/$/, '')}/auth/rnx-cli`)
+      const url = new URL(`${origin.replace(/\/$/, '')}/auth/peach-cli`)
       url.searchParams.set('state', state)
       url.searchParams.set('port', String(address.port))
       url.searchParams.set('contrast', origin)

package/cli/commands/maestro-generate.ts

@@ -18,6 +18,7 @@ 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
@@ -210,10 +211,6 @@ function extractJson(text: string): unknown {
   return JSON.parse(candidate)
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === 'object' && !Array.isArray(value))
-}
-
 function parseGeneratedFlow(text: string): {
   summary: string
   steps: Record<string, unknown>[]

package/cli/commands/maestro.ts

@@ -111,9 +111,12 @@ peach maestro — compatibility matrix
 
 supported verbs:
   launchApp (including arguments), stopApp, clearState, clearKeychain (warn-only),
-  tapOn, tapAtCoords, longPressOn,
+  selectors: text, id, index (negative from the end), childOf, below, above,
+  leftOf, rightOf, width / height / tolerance, traits, enabled, selected, checked,
+  tapOn (including repeat / delay), doubleTapOn, tapAtCoords, longPressOn,
   inputText, pressKey, dispatchKey, hideKeyboard, eraseText,
-  assertVisible, assertNotVisible, assertTreeContains,
+  setClipboard, pasteText,
+  assertVisible, assertNotVisible, assertTrue, assertTreeContains,
   waitFor, extendedWaitUntil, waitForAnimationToEnd,
   scroll, scrollUntilVisible, scrollTo, swipe, pinch,
   takeScreenshot, dumpTree, back,
@@ -158,10 +161,12 @@ partial:
     MAESTRO_* (so \${SOOTSIM_*} credentials resolve); a bare \${NAME} that is
     undefined fails the step loudly instead of typing "undefined".
 
-not yet implemented (will throw "unsupported maestro verb"):
-  travel, setLocation, setAirplaneMode, killApp, faker,
+not yet implemented (the step fails with "unsupported flow step"):
+  travel, setLocation, setAirplaneMode, killApp, faker, inputRandom*,
   addMedia, startRecording, stopRecording (use --record flag),
   repeat.while (only repeat.times is supported).
+selector keys that fail the step: containsChild, containsDescendants,
+  focused, css.
 `)
 }
 
@@ -303,7 +308,9 @@ export function extractMaestroCompatFlags(args: string[]): {
           break
         case '--platform':
           if (value.toLowerCase() !== 'ios') {
-            throw new Error(`peach emulates iOS only; --platform ${value} is not supported`)
+            throw new Error(
+              `peach emulates iOS only; --platform ${value} is not supported`,
+            )
           }
           compat.platform = value
           break
@@ -874,23 +881,33 @@ export async function runMaestro(
     }
 
     const upload = getLastFlowPreviewUploadResult()
-    // the receipt files are the per-flow manifest: always written, with
-    // null ids when the upload failed, so the flow never disappears from
-    // the collected entries.
-    const previewPayload = {
-      flow: path.relative(cwd, file) || file,
-      previewId: upload?.shareId ?? null,
-      previewUrl: upload?.previewUrl ?? null,
-    }
-    try {
-      for (const name of cloudTestResultFileNames('preview', flowIndex, files.length)) {
-        fs.writeFileSync(path.join(cwd, name), JSON.stringify(previewPayload))
+    // only --preview uploads, so only it leaves receipts in the working
+    // directory. they are the per-flow manifest: written with null ids when
+    // the upload failed, so the flow never disappears from the collected
+    // entries.
+    if (args.includes('--preview')) {
+      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
+        failure:
+          exit === 0
+            ? null
+            : failureFromTraceSteps(traceSteps, 'flow playback failed').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) {
+        console.error('  error: required hosted recording upload failed')
+        if (exit === 0) exit = 1
+        if (worstExit === 0) worstExit = 1
       }
-    } catch {}
-    if (!upload?.shareId && !upload?.previewUrl && args.includes('--preview')) {
-      console.error('  error: required hosted recording upload failed')
-      if (exit === 0) exit = 1
-      if (worstExit === 0) worstExit = 1
     }
 
     if (shouldRegisterRun({ uploadedShare: Boolean(upload), auth })) {

package/cli/commands/no-bridge-hint.ts

@@ -1,6 +1,5 @@
 // shared hint printed when the CLI has no bridge or no desktop companion.
 
-import { findDesktopCompanion } from '../desktop-companion'
 import type { BridgeSimInfo } from '../ws-bridge'
 
 export function printMissingCompanionHint() {
@@ -14,19 +13,6 @@ export function printMissingCompanionHint() {
   console.error('')
 }
 
-export function printMissingBridgeHint(port: number) {
-  const companion = findDesktopCompanion()
-  console.log(`  note: no peach bridge detected on port ${port}`)
-  if (companion) {
-    console.log(`  launch the installed companion with:`)
-    console.log(`    peach desktop`)
-    return
-  }
-  console.log('')
-  console.log('  run `peach daemon install` to enable the faster background service,')
-  console.log('  or run `peach serve` in another shell for a foreground bridge.')
-}
-
 export function printMissingSimHint(port: number) {
   console.error('')
   console.error(`  no sim is connected to the peach bridge on port ${port}.`)

package/cli/commands/permissions.ts

@@ -28,7 +28,7 @@ const STATUSES: readonly SystemPermissionStatus[] = [
   'unavailable',
 ]
 
-const KINDS: readonly SystemPermissionKind[] = [
+export const PERMISSION_KINDS: readonly SystemPermissionKind[] = [
   'app-tracking-transparency',
   'bluetooth',
   'calendars',
@@ -71,7 +71,7 @@ function flagValue(args: string[], flag: string): string | undefined {
 }
 
 function permissionKind(value: string): SystemPermissionKind | null {
-  return KINDS.find((candidate) => candidate === value) ?? null
+  return PERMISSION_KINDS.find((candidate) => candidate === value) ?? null
 }
 
 function permissionStatus(value: string): SystemPermissionStatus | null {

package/cli/commands/platform.ts

@@ -460,12 +460,6 @@ async function runRemoteBox(
     apiKey: header.replace(/^Bearer /, ''),
     accountId,
   })
-  // creating a box starts no browser, and only its Browser Run tab hosts the
-  // simulator, so without this the viewer opens onto a box nobody is running.
-  await ensureCloudBoxBrowser({
-    connectUrl: cloudBoxConnectUrl(endpoint, created.id),
-    accessToken: created.accessToken ?? '',
-  })
   const session = createCloudBoxSession({
     boxId: created.id,
     boxToken: created.accessToken ?? '',
@@ -477,6 +471,19 @@ async function runRemoteBox(
       bytes: artifact.bytes.length,
     },
   })
+  // creating a box starts no browser, and only its Browser Run tab hosts the
+  // simulator, so without this the viewer opens onto a box nobody is running.
+  // a box whose browser never started is one nobody can use, and it would
+  // bill until someone found it, so it closes with the failure.
+  try {
+    await ensureCloudBoxBrowser({
+      connectUrl: cloudBoxConnectUrl(endpoint, created.id),
+      accessToken: created.accessToken ?? '',
+    })
+  } catch (error) {
+    await closeCloudBox(session)
+    throw error
+  }
   try {
     publishCloudSessionToShell(session)
   } catch {

package/cli/commands/screenshot.ts

@@ -474,7 +474,12 @@ async function runPlaywrightScreenshot(args: string[], opts: ScreenshotOptions)
   })
 
   try {
-    const page = await browser.newPage({ viewport: { width: 500, height: 900 } })
+    const page = await browser.newPage({
+      viewport: { width: 500, height: 900 },
+      // this fallback screenshots a page a person opens; state display density
+      // so the PNG is retina rather than half of what the display shows.
+      deviceScaleFactor: 2,
+    })
     await page.goto(url, { waitUntil: 'networkidle' })
     await page.waitForTimeout(2000)
 

package/cli/commands/skills.ts

@@ -306,7 +306,7 @@ const LEGACY_BUNDLED_SKILL_DIRS = [
   'sootsim-debug',
   'sootsim-perf',
   'sootsim-test',
-  'sootsim-visual',
+  'peach-visual',
   'rnx-setup',
   'rnx-debug',
   'rnx-perf',

package/cli/commands/test.ts

@@ -572,7 +572,9 @@ async function readJobStatus(
 export async function cancelCloudTest(jobId: string, origin: string): Promise<number> {
   const auth = resolveCliAuth()
   if (!auth) {
-    console.error('  error: cancelling a cloud test requires `peach login` or PEACH_API_KEY')
+    console.error(
+      '  error: cancelling a cloud test requires `peach login` or PEACH_API_KEY',
+    )
     return 1
   }
   const endpoint = `${origin.replace(/\/$/, '')}/api/sootsim/runner/jobs?id=${encodeURIComponent(jobId)}`
@@ -947,7 +949,9 @@ export async function runCloudTest(
       }
     }
 
-    console.error(`  error: cloud test timed out after ${Math.round(timeoutMs / 1000)}s`)
+    console.error(
+      `  error: cloud test timed out after ${timeoutMs < 1000 ? `${timeoutMs}ms` : `${timeoutMs / 1000}s`}`,
+    )
     return 1
   } finally {
     closeTunnel?.()

package/cli/commands/three-mode.ts

@@ -18,6 +18,7 @@ import {
   type WsBridge,
 } from '../ws-bridge'
 import { runShellBooleanMode, type ShellBooleanModeOptions } from './shell-boolean-mode'
+import { isRecord } from '../../src/is-record'
 
 type ThreeModeConfig = Record<string, unknown>
 type ThreeModeState = Record<string, unknown> & {
@@ -97,6 +98,12 @@ measure options (projected bounds only — no pixels rendered):
   --at <ms[,ms...]>      sample exact timeline times (overrides from/to/count)
   --output <file.json>   write the measurement JSON here instead of stdout
 
+asset delivery:
+  local recording/screenshot files referenced by the timeline upload once per
+  distinct file in ~1mb chunks; the page serves them back as blob: urls.
+  a later command against the same page reuses them without re-uploading.
+  uploads need a development build of the page; production drops the bridge.
+
 examples:
   peach mode three
   peach mode three on
@@ -328,10 +335,6 @@ function readNumberFlag(args: string[], flag: string, fallback: number, minimum
   return value
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
 function mimeTypeForAsset(path: string, contentType: unknown) {
   const extension = extname(path).toLowerCase()
   if (contentType === 'recording') {
@@ -343,36 +346,171 @@ function mimeTypeForAsset(path: string, contentType: unknown) {
   return 'image/png'
 }
 
-function inlineTimelineAssets(value: unknown, baseDirectory: string): unknown {
+// the ws bridge server caps inbound messages at its 100 MiB maxPayload, so a
+// timeline with base64-inlined assets closes the socket (code 1009) once the
+// clips grow past it. local assets travel in 1 MiB raw chunks instead — each
+// bridge message stays near 1.4 MB — and the page serves them back to the
+// timeline as blob: URLs.
+const TIMELINE_ASSET_CHUNK_BYTES = 1_048_576
+
+type TimelineAssetRef = {
+  src: string
+  recording: boolean
+}
+
+function timelineAssetRefOf(value: Record<string, unknown>): TimelineAssetRef | null {
+  if (
+    (value.type === 'recording' ||
+      value.type === 'screenshot' ||
+      value.kind === 'screen') &&
+    typeof value.src === 'string' &&
+    !/^(?:blob:|data:|https?:)/i.test(value.src)
+  ) {
+    return { src: value.src, recording: value.type === 'recording' }
+  }
+  return null
+}
+
+function collectTimelineAssetRefs(value: unknown): TimelineAssetRef[] {
+  const refs: TimelineAssetRef[] = []
+  const seen = new Set<string>()
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (const entry of node) visit(entry)
+      return
+    }
+    if (!isRecord(node)) return
+    for (const entry of Object.values(node)) visit(entry)
+    const ref = timelineAssetRefOf(node)
+    if (ref && !seen.has(ref.src)) {
+      seen.add(ref.src)
+      refs.push(ref)
+    }
+  }
+  visit(value)
+  return refs
+}
+
+type DistinctTimelineAsset = {
+  hash: string
+  mime: string
+  bytes: Buffer
+  srcs: string[]
+}
+
+function readDistinctTimelineAssets(
+  value: unknown,
+  baseDirectory: string,
+): DistinctTimelineAsset[] {
+  const byHash = new Map<string, DistinctTimelineAsset>()
+  for (const ref of collectTimelineAssetRefs(value)) {
+    const assetPath = resolve(baseDirectory, ref.src)
+    const bytes = readFileSync(assetPath)
+    const hash = createHash('sha256').update(bytes).digest('hex')
+    const existing = byHash.get(hash)
+    if (existing) {
+      existing.srcs.push(ref.src)
+      continue
+    }
+    byHash.set(hash, {
+      hash,
+      mime: mimeTypeForAsset(assetPath, ref.recording ? 'recording' : 'screenshot'),
+      bytes,
+      srcs: [ref.src],
+    })
+  }
+  return [...byHash.values()]
+}
+
+function rewriteTimelineAssetSrcs(
+  value: unknown,
+  urlBySrc: Map<string, string>,
+): unknown {
   if (Array.isArray(value)) {
-    return value.map((entry) => inlineTimelineAssets(entry, baseDirectory))
+    return value.map((entry) => rewriteTimelineAssetSrcs(entry, urlBySrc))
   }
   if (!isRecord(value)) return value
 
   const result: Record<string, unknown> = {}
   for (const [key, entry] of Object.entries(value)) {
-    result[key] = inlineTimelineAssets(entry, baseDirectory)
+    result[key] = rewriteTimelineAssetSrcs(entry, urlBySrc)
   }
-  if (
-    (result.type === 'recording' ||
-      result.type === 'screenshot' ||
-      result.kind === 'screen') &&
-    typeof result.src === 'string' &&
-    !/^(?:blob:|data:|https?:)/i.test(result.src)
-  ) {
-    const assetPath = resolve(baseDirectory, result.src)
-    const bytes = readFileSync(assetPath)
-    result.src = `data:${mimeTypeForAsset(assetPath, result.type === 'recording' ? 'recording' : 'screenshot')};base64,${bytes.toString('base64')}`
+  const ref = timelineAssetRefOf(result)
+  if (ref) {
+    const url = urlBySrc.get(ref.src)
+    if (url) result.src = url
   }
   return result
 }
 
+type TimelineAssetUploadResult = {
+  hash: string
+  url: string | null
+}
+
+async function uploadTimelineAssets(
+  bridge: WsBridge,
+  timeline: unknown,
+  baseDirectory: string,
+): Promise<unknown> {
+  const assets = readDistinctTimelineAssets(timeline, baseDirectory)
+  const urlBySrc = new Map<string, string>()
+  for (const asset of assets) {
+    const shortHash = asset.hash.slice(0, 12)
+    const known = await callInBridgeWrite<TimelineAssetUploadResult>(
+      bridge,
+      'SootSim.bridges.threeMode.uploadAsset',
+      { op: 'has', hash: asset.hash },
+    )
+    if (known?.url) {
+      console.log(
+        `  three-mode: reusing uploaded asset ${shortHash} (${asset.bytes.length} bytes, upload skipped)`,
+      )
+      for (const src of asset.srcs) urlBySrc.set(src, known.url)
+      continue
+    }
+    await callInBridgeWrite(bridge, 'SootSim.bridges.threeMode.uploadAsset', {
+      op: 'begin',
+      hash: asset.hash,
+      mime: asset.mime,
+      bytes: asset.bytes.length,
+    })
+    const chunks = Math.max(1, Math.ceil(asset.bytes.length / TIMELINE_ASSET_CHUNK_BYTES))
+    for (let index = 0; index < chunks; index += 1) {
+      const slice = asset.bytes.subarray(
+        index * TIMELINE_ASSET_CHUNK_BYTES,
+        (index + 1) * TIMELINE_ASSET_CHUNK_BYTES,
+      )
+      await callInBridgeWrite(bridge, 'SootSim.bridges.threeMode.uploadAsset', {
+        op: 'chunk',
+        hash: asset.hash,
+        index,
+        base64: slice.toString('base64'),
+      })
+    }
+    const finished = await callInBridgeWrite<TimelineAssetUploadResult>(
+      bridge,
+      'SootSim.bridges.threeMode.uploadAsset',
+      { op: 'finish', hash: asset.hash },
+    )
+    if (!finished?.url) {
+      throw new Error(`three-mode asset upload finished without a URL for ${shortHash}`)
+    }
+    console.log(
+      `  three-mode: uploaded asset ${shortHash} (${asset.bytes.length} bytes in ${chunks} chunks)`,
+    )
+    for (const src of asset.srcs) urlBySrc.set(src, finished.url)
+  }
+  return rewriteTimelineAssetSrcs(timeline, urlBySrc)
+}
+
 function readTimelineFile(path: string) {
   const absolutePath = resolve(path)
   const parsed: unknown = JSON.parse(readFileSync(absolutePath, 'utf8'))
   return {
     absolutePath,
-    timeline: inlineTimelineAssets(parsed, dirname(absolutePath)),
+    timeline: parsed,
+    baseDirectory: dirname(absolutePath),
   }
 }
 
@@ -434,10 +572,15 @@ async function runThreeModeTimelineAction(
     if (!timelinePath)
       throw new Error(`three-mode ${action} expects a timeline JSON path`)
     const loadedFile = readTimelineFile(timelinePath)
+    const timeline = await uploadTimelineAssets(
+      bridge,
+      loadedFile.timeline,
+      loadedFile.baseDirectory,
+    )
     const loaded = await callInBridgeWrite<TimelineSampleResult>(
       bridge,
       'SootSim.bridges.threeMode.loadTimeline',
-      loadedFile.timeline,
+      timeline,
     )
     if (action === 'load') {
       console.log(

package/cli/commands/upload.ts

@@ -21,6 +21,7 @@ import {
   isTraceTimelineEvent,
   parseTraceTimelineJsonl,
 } from 'peach-engine/preview/trace'
+import { loopbackOriginOf } from '../../src/backend-origin'
 import { rnxPublicBrand } from '../../src/public-brand'
 import { fetchAppFontFiles } from '../app-fonts'
 import { fetchAppSplashImages } from '../app-splash'
@@ -115,7 +116,7 @@ function readSnapshotManifest(manifestPath: string): AttachedInteractionSnapshot
 
 const REMOTE_DEFAULT_ORIGIN = process.env.PEACH_UPLOAD_ORIGIN || 'https://contrast.dev'
 // the canonical public preview link. Uploads go to the contrast backend, but
-// reviewers/users open rnx preview pages on rnxsim.com.
+// reviewers/users open rnx preview pages on peachsim.com.
 const REMOTE_DEFAULT_PUBLIC_PREVIEW_ORIGIN =
   process.env.PEACH_PREVIEW_ORIGIN || rnxPublicBrand.origin
 export async function resolveDefaultUploadOrigin(
@@ -130,22 +131,6 @@ function normalizeOrigin(origin: string): string {
   return origin.replace(/\/$/, '')
 }
 
-function isLoopbackOrigin(origin: string): boolean {
-  try {
-    const parsed = new URL(origin)
-    const hostname = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase()
-    return (
-      hostname === 'localhost' ||
-      hostname.endsWith('.localhost') ||
-      hostname === '0.0.0.0' ||
-      hostname === '::1' ||
-      /^127(?:\.\d{1,3}){3}$/.test(hostname)
-    )
-  } catch {
-    return false
-  }
-}
-
 function isContrastOrigin(origin: string): boolean {
   try {
     const hostname = new URL(origin).hostname.toLowerCase()
@@ -163,7 +148,7 @@ export function resolvePublicPreviewOrigin(
   if (process.env.PEACH_PREVIEW_ORIGIN) {
     return normalizeOrigin(process.env.PEACH_PREVIEW_ORIGIN)
   }
-  if (isLoopbackOrigin(uploadOrigin)) return normalizeOrigin(uploadOrigin)
+  if (loopbackOriginOf(uploadOrigin) !== null) return normalizeOrigin(uploadOrigin)
   if (isContrastOrigin(uploadOrigin)) {
     return normalizeOrigin(REMOTE_DEFAULT_PUBLIC_PREVIEW_ORIGIN)
   }

package/cli/current-sim.ts

@@ -19,7 +19,6 @@ export interface LocalCurrentTarget {
 // progressively weaker signal of "same caller across invocations".
 const IDENTITY_ENV_VARS = [
   'PEACH_CLI_IDENTITY', // explicit override — fastest path, skips all pid lookups
-  'TM_SESSION', // Team Machine session id; routes prompt-bar followups back to this agent
   'CLAUDE_CODE_SESSION_ID', // claude code, if ever set
   'CODEX_THREAD_ID', // codex / openai agent thread, stable across tool invocations
   'TERM_SESSION_ID', // macOS Terminal.app + iTerm2

package/cli/desktop-companion.ts

@@ -89,12 +89,10 @@ function findElectronBin(startDir: string): string | null {
   return null
 }
 
-function findMacApp(): DesktopCompanionInstall | null {
-  const root = getSootsimRoot()
+function findInstalledMacApp(): DesktopCompanionInstall | null {
   const candidates = [
     '/Applications/peach.app',
     resolve(process.env.HOME || '', 'Applications/peach.app'),
-    ...(root ? [resolve(root, 'app/peach.app')] : []),
   ]
 
   const found = candidates.find((candidate) => existsSync(candidate))
@@ -106,6 +104,18 @@ function findMacApp(): DesktopCompanionInstall | null {
     }
   }
 
+  return null
+}
+
+function findMacApp(): DesktopCompanionInstall | null {
+  const installed = findInstalledMacApp()
+  if (installed) return installed
+  const root = getSootsimRoot()
+  const builtApp = root ? resolve(root, 'app/peach.app') : null
+  if (builtApp && existsSync(builtApp)) {
+    return { path: builtApp, platform: 'darwin', kind: 'mac-app' }
+  }
+
   try {
     const result = execFileSync(
       'mdfind',
@@ -124,6 +134,13 @@ function findMacApp(): DesktopCompanionInstall | null {
   return null
 }
 
+export function findInstalledDesktopCompanion(): DesktopCompanionInstall | null {
+  if (process.platform === 'darwin') return findInstalledMacApp()
+  if (process.platform === 'linux') return findInstalledLinuxApp()
+  if (process.platform === 'win32') return findWindowsInstall()
+  return null
+}
+
 function findFirstAppImage(dir: string): string | null {
   if (!existsSync(dir)) return null
   const match = readdirSync(dir)
@@ -133,16 +150,12 @@ function findFirstAppImage(dir: string): string | null {
   return match ? join(dir, match) : null
 }
 
-function findLinuxInstall(): DesktopCompanionInstall | null {
-  const root = getSootsimRoot()
+function findInstalledLinuxApp(): DesktopCompanionInstall | null {
   const directCandidates = [
     resolve(process.env.HOME || '', 'Applications/peach.AppImage'),
     resolve(process.env.HOME || '', '.local/bin/peach.AppImage'),
     '/opt/peach/peach.AppImage',
     '/opt/peach/peach',
-    ...(root
-      ? [resolve(root, 'app/peach.AppImage'), resolve(root, 'release/linux-unpacked/peach')]
-      : []),
   ]
 
   const directMatch = directCandidates.find((candidate) => existsSync(candidate))
@@ -154,6 +167,25 @@ function findLinuxInstall(): DesktopCompanionInstall | null {
     }
   }
 
+  return null
+}
+
+function findLinuxInstall(): DesktopCompanionInstall | null {
+  const installed = findInstalledLinuxApp()
+  if (installed) return installed
+  const root = getSootsimRoot()
+  const directCandidates = root
+    ? [resolve(root, 'app/peach.AppImage'), resolve(root, 'release/linux-unpacked/peach')]
+    : []
+  const directMatch = directCandidates.find((candidate) => existsSync(candidate))
+  if (directMatch) {
+    return {
+      path: directMatch,
+      platform: 'linux',
+      kind: directMatch.endsWith('.AppImage') ? 'linux-appimage' : 'linux-binary',
+    }
+  }
+
   const scannedMatch = root
     ? findFirstAppImage(resolve(root, 'app')) ||
       findFirstAppImage(resolve(root, 'release'))

package/cli/drivers/playwright-provisioning.ts

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import { RNX_INTERNAL_CHILDREN, RNX_INTERNAL_COMMAND } from '../internal-child'
 import { rnxSelfInvocation } from '../self-invocation'
+import { isRecord } from '../../src/is-record'
 
 export interface ResolvedPlaywright {
   // package name that resolved (for human-facing messaging)
@@ -27,10 +28,6 @@ export type PlaywrightBrowserProvisioningResult =
       message: string
     }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
 export function resolvePlaywright(): ResolvedPlaywright | null {
   // resolve from several roots, not just cwd. a user can invoke a global CLI
   // from an arbitrary directory while Playwright is installed beside the CLI.