peachsim 0.1.1594 → 0.1.1620

package/cli/commands/control.ts

@@ -45,7 +45,9 @@ import {
   runtimesDir,
 } from '../../src/home-paths'
 import { projectLoopbackUrl } from '../../src/host/loopback-ports'
+import { stageHostFile } from '../../src/host/staged-host-files'
 import { readInstalledNativePackageVersions } from '../../src/installed-package-versions'
+import { detectBundleModeFromText } from '../../src/metro-production-bundle'
 import {
   canExtractNativeAppIdentity,
   createNativeAppIdentityHeader,
@@ -59,6 +61,7 @@ import {
   readExpoConfigAsync,
   readNativeFirebaseConfig,
 } from '../../src/native-firebase-config'
+import { isProcessRunning } from '../../src/process-liveness'
 import { ensureProfile } from '../../src/profiles'
 import { rnxPublicBrand } from '../../src/public-brand'
 import {
@@ -115,6 +118,7 @@ import {
 import { readNativeProjectRenderer } from './detect'
 import { inspectDescribe, inspectReadySnapshot, waitReadyReason } from './inspect/core'
 import { isAgentEnv } from './inspect/env'
+import { waitForSimReady } from './inspect/shared'
 import { hasInstalledPeachSkills } from './skills'
 import type { DriverId, DriverLaunchResult } from '../drivers/types'
 
@@ -144,6 +148,11 @@ const DRIVER_CONNECT_INTERVAL_MS = 100
 const DRIVER_CONNECT_HOST_GRACE_MS = 5_000
 const OPEN_BRIDGE_SPAWN_TIMEOUT_MS = 10_000
 const OPEN_BRIDGE_RUNTIME_TIMEOUT_MS = 120_000
+// a closed port refuses at once, so this window only matters when something
+// listens: a live bridge on a loaded machine can take longer than 250 ms to
+// finish the handshake, and missing it spawned a second bridge or reported a
+// live daemon as unreachable.
+const LIVE_BRIDGE_HANDSHAKE_TIMEOUT_MS = 2_000
 
 // built-in shell apps use pathname-based routing, not ?bundle= params
 const SHELL_APPS: Record<string, string> = {
@@ -235,7 +244,10 @@ export async function ensureBridgeForOpen(
   )
   // a bridge accepts connections while its first runtime download is still
   // running, and every shell page answers 503 until that finishes.
-  if (runtimeSource === 'bridge') await waitForBridgeRuntime(port)
+  if (runtimeSource === 'bridge') {
+    await waitForBridgeRuntime(port)
+    await ensureRuntimeForOpen()
+  }
   return port
 }
 
@@ -262,13 +274,8 @@ async function connectBridgeForOpen(
 ): Promise<number> {
   const lock = readDaemonLockfile()
   assertExplicitBridgeLock(preferredPort, explicitPort, lock)
-  // an explicit shell origin owns its assets; the bridge only routes commands.
-  if (runtimeSource === 'bridge') await ensureRuntimeForOpen()
   const preferredWorld = worldForBridgePort(preferredPort)
-  // a closed port refuses at once, so this window only matters when something
-  // listens: a live bridge on a loaded machine can take longer than 250 ms to
-  // finish the handshake, and missing it spawned a second bridge.
-  const handshake = await bridgeHandshake(preferredPort, 2_000)
+  const handshake = await bridgeHandshake(preferredPort, LIVE_BRIDGE_HANDSHAKE_TIMEOUT_MS)
   if ((explicitPort || preferredWorld !== null) && handshake === 'open') {
     return preferredPort
   }
@@ -279,7 +286,9 @@ async function connectBridgeForOpen(
     !explicitPort &&
     lock &&
     isDaemonLockfileFresh(lock) &&
-    (await canConnectToBridge(lock.bridgePort, 500))
+    (lock.bridgePort === preferredPort
+      ? handshake === 'open'
+      : await canConnectToBridge(lock.bridgePort, LIVE_BRIDGE_HANDSHAKE_TIMEOUT_MS))
   ) {
     return lock.bridgePort
   }
@@ -289,6 +298,9 @@ async function connectBridgeForOpen(
     )
   }
 
+  // starting a bridge needs ready local assets; an existing bridge gets
+  // to finish its own install before the caller validates them.
+  if (runtimeSource === 'bridge') await ensureRuntimeForOpen()
   const { executable, prefixArgs } = rnxSelfInvocation()
   // the bridge outlives open, so it must not hold the command's captured stderr.
   const bridgeLogPath = path.join(
@@ -510,7 +522,12 @@ function buildShellPathOpenUrl(target: string, baseUrl: string): string {
     : targetUrl.pathname
 
   url.pathname = `${prefix}${routePath}`
+  const baseDemo = url.searchParams.getAll('demo')
   url.search = targetUrl.search
+  // demo also sets embed chrome around native routes; a target can override it.
+  if (!targetUrl.searchParams.has('demo')) {
+    for (const demo of baseDemo) url.searchParams.append('demo', demo)
+  }
   url.hash = targetUrl.hash
   return url.toString()
 }
@@ -639,7 +656,6 @@ function buildConnectOpenUrl(target: string, baseUrl: string): string {
 
   url.pathname = `${prefix}/rn`
   url.searchParams.delete('bundle')
-  url.searchParams.delete('demo')
   url.searchParams.delete('app')
   url.searchParams.delete('open')
   url.searchParams.delete('port')
@@ -666,6 +682,39 @@ function shouldResolveBundleTargetInCli(target: string): boolean {
   )
 }
 
+// a built bundle on disk (`peach open ./dist/ios.js`). the bridge serves a
+// staged copy, so it loads with no dev server running.
+function prebuiltBundleFile(target: string): string | null {
+  if (!/\.(js|bundle|jsbundle)$/i.test(target)) return null
+  const file = path.resolve(process.cwd(), target)
+  return fs.statSync(file, { throwIfNoEntry: false })?.isFile() ? file : null
+}
+
+// the nearest app above the bundle supplies its fonts, splash and identity
+function appDirAbove(file: string): string | undefined {
+  for (let dir = path.dirname(file); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+    if (resolveAppProject(dir)) return dir
+  }
+  return undefined
+}
+
+// the url names the bundle's own mode, so the engine boots the matching
+// tenant first instead of restarting into it after the fetch.
+async function stagePrebuiltBundle(
+  file: string,
+  bridgePort: number,
+): Promise<ResolvedDevBundle> {
+  const mode = await detectBundleModeFromText(fs.readFileSync(file, 'utf8'))
+  if (!mode) {
+    throw new Error(
+      `${file} carries no __DEV__ prelude or Metro module shape, so its development or production build cannot be told apart`,
+    )
+  }
+  const url = new URL(stageHostFile(file, `http://localhost:${bridgePort}`))
+  url.searchParams.set('dev', String(mode === 'development'))
+  return { bundleUrl: url.toString(), port: bridgePort, framework: 'unknown' }
+}
+
 async function buildResolvedBundleOpenUrl(
   target: string,
   baseUrl: string,
@@ -677,7 +726,6 @@ async function buildResolvedBundleOpenUrl(
   url.pathname = `${prefix}/rn`
   url.searchParams.delete('open')
   url.searchParams.delete('port')
-  url.searchParams.delete('demo')
   url.searchParams.delete('app')
   const bundleUrl =
     opts.hot === undefined
@@ -809,7 +857,12 @@ export function resolveShellBaseUrlForBridgePort(bridgePort: number): string {
 // fetches itself. auto-discovery only — scans the repo for expo-font config
 // plugin declarations, no user-facing flag. discovery keeps only font files
 // that exist on disk, so the stamp never waits on the dev server.
-function stampAppFonts(urlStr: string, project?: ResolvedAppProject | null): string {
+function stampAppFonts(
+  urlStr: string,
+  platform: 'ios' | 'android',
+  nativeAssetOrigin: string,
+  project?: ResolvedAppProject | null,
+): string {
   try {
     const url = new URL(urlStr)
     const bundleUrl = url.searchParams.get('bundle') || ''
@@ -817,6 +870,8 @@ function stampAppFonts(urlStr: string, project?: ResolvedAppProject | null): str
     const specs = discoverNativeLinkedAppFonts({
       bundleUrl,
       projectDir: project.appDir,
+      platform,
+      nativeAssetOrigin,
     })
     if (specs.length === 0) return urlStr
     url.searchParams.set('appFonts', encodeAppFontsWire(specs))
@@ -1095,21 +1150,32 @@ export async function buildShellUrl(
   const project =
     opts.project ?? (await resolveAppProjectForBundleUrl(bundleUrlOf(resolved)))
   const expoRoot = project?.appDir ?? null
+  const world = resolveBridgeWorld()
+  const port = resolveBridgePortForPin({
+    baseUrl,
+    wsPort: opts.bridgePort ?? world.bridgePort,
+    explicitPort: opts.bridgePort !== undefined,
+  })
+  if (project && port.error) throw new Error(port.error)
+  const device = opts.device ?? new URL(resolved).searchParams.get('device')
+  const bundle = bundleUrlOf(resolved)
+  const platform =
+    device && isDeviceModel(device)
+      ? getRuntimePlatform(device)
+      : bundle && new URL(bundle).searchParams.get('platform') === 'android'
+        ? 'android'
+        : 'ios'
   const stamped = stampAppCatalog(
-    await stampAppSplash(stampAppFonts(resolved, project), project, opts.oneAppSplash),
+    await stampAppSplash(
+      stampAppFonts(resolved, platform, `http://localhost:${port.port}`, project),
+      project,
+      opts.oneAppSplash,
+    ),
     project,
   )
   const expoStamped = new URL(stamped)
   expoStamped.searchParams.delete('nativeAppIdentity')
   if (project) {
-    const device = opts.device ?? expoStamped.searchParams.get('device')
-    const bundle = bundleUrlOf(resolved)
-    const platform =
-      device && isDeviceModel(device)
-        ? getRuntimePlatform(device)
-        : bundle && new URL(bundle).searchParams.get('platform') === 'android'
-          ? 'android'
-          : 'ios'
     const nativeRenderer = readNativeProjectRenderer(project.appDir, platform)
     if (nativeRenderer !== undefined) {
       const config = readPeachConfigFromSearchParams(expoStamped.searchParams)
@@ -1148,13 +1214,6 @@ export async function buildShellUrl(
     expoStamped.searchParams.set('bundleOriginOverride', opts.bundleOriginOverride)
   if (opts.hostDriver) expoStamped.searchParams.set('peachHostDriver', opts.hostDriver)
   if (expoRoot) {
-    const world = resolveBridgeWorld()
-    const port = resolveBridgePortForPin({
-      baseUrl,
-      wsPort: opts.bridgePort ?? world.bridgePort,
-      explicitPort: opts.bridgePort !== undefined,
-    })
-    if (port.error) throw new Error(port.error)
     expoStamped.searchParams.set(
       'expoSwift',
       `http://localhost:${port.port}/__peach/expo-swift?root=${encodeURIComponent(expoRoot)}`,
@@ -1198,7 +1257,8 @@ function deriveCurrentSimBaseUrl(
   try {
     const url = new URL(source)
     url.searchParams.delete('bundle')
-    url.searchParams.delete('demo')
+    // demo is embed chrome around the next target, like device/theme: the
+    // selected-sim rebuild keeps it unless the target overrides it.
     url.searchParams.delete('app')
     url.searchParams.delete('open')
     url.searchParams.delete('port')
@@ -1232,65 +1292,6 @@ function withOpenToken(shellUrl: string, openToken: string): string {
   return url.toString()
 }
 
-async function waitForSimReady(
-  wsPort: number,
-  commandTimeoutMs: number,
-  simId: string,
-  opts: {
-    attempts?: number
-    intervalMs?: number
-    minNodeCount?: number
-  } = {},
-) {
-  // the ceiling here is attempts * intervalMs. a hosted launchApp re-evals the
-  // whole guest bundle over a tunnel, which routinely outlasts the local
-  // default, so scale the poll ceiling by the same factor the flow runner
-  // scales its own waits. this still returns the moment the sim reports enough
-  // nodes; only the deadline moves, and locally the scale is 1.
-  const intervalMs = opts.intervalMs ?? 500
-  const attempts = opts.attempts ?? Math.round(30 * flowTimeoutScale())
-  const minNodeCount = opts.minNodeCount ?? 10
-
-  // a poll that only ever reports "timed out" cannot say whether the guest was
-  // still booting, never installed the test hook, or was unreachable, so keep
-  // the last observation and hand it to the caller for the failure message.
-  let lastCount: unknown
-  let lastError = ''
-
-  for (let i = 0; i < attempts; i++) {
-    const bridge = createBridge(wsPort, {
-      commandTimeoutMs,
-      simId,
-      simIdSource: 'flag',
-    })
-    try {
-      const count = await bridge.send({
-        type: 'evaluate',
-        code: '(async () => (await window.__sootsimTest?.getNodeCount()) ?? null)()',
-      })
-      lastCount = count
-      lastError = ''
-      if (typeof count === 'number' && count > minNodeCount) {
-        return { bridge, count }
-      }
-    } catch (err) {
-      lastError = err instanceof Error ? err.message : String(err)
-    }
-    bridge.close()
-    await sleep(intervalMs)
-  }
-
-  const observed = lastError
-    ? `last bridge error: ${lastError}`
-    : lastCount === null
-      ? 'guest never installed window.__sootsimTest'
-      : `last node count: ${String(lastCount)} (needs > ${minNodeCount})`
-  return {
-    bridge: null,
-    failure: `after ${attempts} polls over ${Math.round((attempts * intervalMs) / 1000)}s; ${observed}`,
-  }
-}
-
 export async function waitForSimMatch(
   wsPort: number,
   commandTimeoutMs: number,
@@ -1335,7 +1336,8 @@ export async function waitForSimMatchOrHostExit(
   const attempts = opts.attempts ?? 30
   const intervalMs = opts.intervalMs ?? 500
   const watchHost = !!hostPid && Number.isInteger(hostPid) && hostPid > 1
-  const hostExited = () => watchHost && hostPid !== undefined && !isProcessAlive(hostPid)
+  const hostExited = () =>
+    watchHost && hostPid !== undefined && !isProcessRunning(hostPid)
   for (let i = 0; i < attempts; i++) {
     opts.signal?.throwIfAborted()
     if (hostExited()) {
@@ -1444,22 +1446,13 @@ export function printDriverDiagnosticLogTail(result: DriverLaunchResult) {
   }
 }
 
-function isProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0)
-    return true
-  } catch (err) {
-    return (err as NodeJS.ErrnoException)?.code === 'EPERM'
-  }
-}
-
 async function waitForProcessExit(pid: number, timeoutMs = 2_500): Promise<boolean> {
   const deadline = Date.now() + timeoutMs
   while (Date.now() < deadline) {
-    if (!isProcessAlive(pid)) return true
+    if (!isProcessRunning(pid)) return true
     await sleep(100)
   }
-  return !isProcessAlive(pid)
+  return !isProcessRunning(pid)
 }
 
 // a sim record's host pid can outlive its process; after pid reuse the number
@@ -1468,6 +1461,17 @@ async function waitForProcessExit(pid: number, timeoutMs = 2_500): Promise<boole
 // whole dev stack down). only signal a pid whose argv proves it is still a
 // peach playwright host launcher.
 function isPlaywrightHostProcess(pid: number): boolean {
+  // linux reads the environment from /proc: container images often ship no ps.
+  if (process.platform === 'linux') {
+    try {
+      return fs
+        .readFileSync(`/proc/${pid}/environ`, 'utf8')
+        .split('\0')
+        .some((entry) => entry.startsWith('SOOTSIM_PW_URL='))
+    } catch {
+      return false
+    }
+  }
   // `ps eww` prints argv then the process ENVIRONMENT for same-user
   // processes. the marker must live in the env SUFFIX (everything past the
   // plain argv), because argv text can contain the string coincidentally —
@@ -1637,7 +1641,6 @@ async function maybeDescribeAfterOpen(wsPort: number, simId: string, args: strin
         filter: '',
         compact: true,
         hideXy: false,
-        maxDepth: 12,
       })
       if (!result?.tree) return
       console.log('')
@@ -1876,9 +1879,12 @@ export async function runOpenCommand(
     return
   }
 
-  const resolvedBundle = shouldResolveBundleTargetInCli(target)
-    ? await resolveConnectionInputForCli(target)
-    : undefined
+  const prebuiltBundle = prebuiltBundleFile(target)
+  // a bundle file gets its url once the bridge that serves it is settled
+  let resolvedBundle =
+    !prebuiltBundle && shouldResolveBundleTargetInCli(target)
+      ? await resolveConnectionInputForCli(target)
+      : undefined
   const projectRootIndex = args.indexOf('--project-root')
   const projectRoot = projectRootIndex < 0 ? undefined : args[projectRootIndex + 1]
   if (projectRootIndex >= 0 && (!projectRoot || projectRoot.startsWith('--'))) {
@@ -1887,7 +1893,7 @@ export async function runOpenCommand(
   }
   const project = await resolveAppProjectForBundleUrl(
     resolvedBundle?.bundleUrl,
-    projectRoot,
+    projectRoot ?? (prebuiltBundle ? appDirAbove(prebuiltBundle) : undefined),
   )
   startNativeFirebaseConfigRead(project)
   // playwright is the browser-sim launcher. it owns an isolated profile and
@@ -2000,10 +2006,25 @@ export async function runOpenCommand(
     parsed.wsPort,
     parsed.explicitPort,
     opts.resources,
-    explicitBaseUrl && !configuredRuntimeVersion ? 'external' : 'bridge',
+    !configuredRuntimeVersion && (explicitBaseUrl || looksLikeSootsimUrl(target))
+      ? 'external'
+      : 'bridge',
   )
   if (opts.resources) opts.resources.port = parsed.wsPort
   opts.signal?.throwIfAborted()
+  // the shell opens a bundle file as the url the bridge serves it at
+  let shellTarget = target
+  if (prebuiltBundle) {
+    try {
+      resolvedBundle = await stagePrebuiltBundle(prebuiltBundle, parsed.wsPort)
+      shellTarget = resolvedBundle.bundleUrl
+    } catch (error) {
+      console.error(
+        `  peach open: ${error instanceof Error ? error.message : String(error)}`,
+      )
+      peachExit(1)
+    }
+  }
 
   // --posture <open|closed> seeds the fold posture for the opened sim,
   // stamped on the engine URL next to ?device= so it round-trips instead of
@@ -2179,7 +2200,7 @@ export async function runOpenCommand(
         }
         if (!targetSim && parsed.simIdSource !== 'flag') {
           targetShellUrl = newSimShellUrl = await buildShellUrl(
-            target,
+            shellTarget,
             applyPeachConfigToUrl(baseUrl, runtimeConfig),
             buildShellUrlOpts,
           )
@@ -2218,7 +2239,7 @@ export async function runOpenCommand(
           navigatedShellUrl =
             targetShellUrl ??
             (await buildShellUrl(
-              target,
+              shellTarget,
               applyPeachConfigToUrl(resolvedBaseUrl, runtimeConfig),
               buildShellUrlOpts,
             ))
@@ -2278,6 +2299,7 @@ export async function runOpenCommand(
           parsed.wsPort,
           parsed.commandTimeoutMs,
           targetSim.id,
+          { attempts: Math.round(30 * flowTimeoutScale()), simIdSource: 'flag' },
         )
         if (!ready.bridge) {
           console.error(
@@ -2309,7 +2331,8 @@ export async function runOpenCommand(
 
   const configuredBaseUrl = applyPeachConfigToUrl(baseUrl, runtimeConfig)
   const openUrl = withOpenToken(
-    newSimShellUrl ?? (await buildShellUrl(target, configuredBaseUrl, buildShellUrlOpts)),
+    newSimShellUrl ??
+      (await buildShellUrl(shellTarget, configuredBaseUrl, buildShellUrlOpts)),
     token,
   )
   const ownerPid = opts.ownerPid ?? getStableOwnerPid()
@@ -2401,6 +2424,7 @@ export async function runOpenCommand(
   const ready = await waitForSimReady(parsed.wsPort, parsed.commandTimeoutMs, match.id, {
     intervalMs: connectWait.intervalMs,
     attempts: connectWait.attempts,
+    simIdSource: 'flag',
   })
   if (!ready.bridge) {
     console.error(

package/cli/commands/daemon.ts

@@ -24,6 +24,7 @@ import {
   readlinkSync,
   realpathSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'fs'
 import { homedir } from 'os'
@@ -365,6 +366,91 @@ function macBridgeHasListener(pid: number, port: number): boolean {
   return result.stdout.trim() === String(pid)
 }
 
+// a process runs this invocation's `serve` when its executable is the same
+// file and its arguments start with the entry script and `serve`. argv[0] is
+// spelled however the spawner named the file (a symlinked /tmp, a bin shim,
+// a relative path) while process.execPath is resolved, so the executable is
+// compared by device and inode, never by path text. inodes on the system
+// volume exceed 2^53, so both compare as bigints.
+function sameFile(path: string, device: bigint, inode: bigint): boolean {
+  try {
+    const stats = statSync(path, { bigint: true })
+    return stats.dev === device && stats.ino === inode
+  } catch {
+    return false
+  }
+}
+
+function serveArgs(invocation: RnxSelfInvocation): string[] {
+  return [...invocation.prefixArgs, 'serve']
+}
+
+function macProcessRunsServe(pid: number, invocation: RnxSelfInvocation): boolean {
+  // lsof names each mapped text file by device and inode; the executable is one.
+  const files = spawnSync('lsof', ['-nP', '-a', '-p', String(pid), '-d', 'txt', '-FDi'], {
+    encoding: 'utf8',
+  })
+  let device = -1n
+  let runsExecutable = false
+  for (const line of files.stdout.split('\n')) {
+    if (line.startsWith('D')) device = BigInt(line.slice(1))
+    else if (
+      line.startsWith('i') &&
+      sameFile(invocation.executable, device, BigInt(line.slice(1)))
+    )
+      runsExecutable = true
+  }
+  if (!runsExecutable) return false
+  const args = macProcessArgs(pid)
+  return (
+    args !== null && serveArgs(invocation).every((arg, index) => args[index + 1] === arg)
+  )
+}
+
+// the kernel's exact argv vector (KERN_PROCARGS2: argc, executable path, then
+// argc NUL-terminated arguments), read through the system JXA Foundation
+// bridge. `ps` flattens argv with spaces and cannot recover argument
+// boundaries.
+function macProcessArgs(pid: number): string[] | null {
+  const int32 = (value: number) => {
+    const bytes = Buffer.alloc(4)
+    bytes.writeUInt32LE(value)
+    return bytes
+  }
+  const capacity = 1 << 20 // ARG_MAX
+  const mib = Buffer.concat([int32(1), int32(49), int32(pid)]).toString('base64')
+  const size = Buffer.alloc(8)
+  size.writeBigUInt64LE(BigInt(capacity))
+  const script = `
+ObjC.import('Foundation');
+ObjC.bindFunction('sysctl', ['int', ['void *', 'unsigned int', 'void *', 'void *', 'void *', 'unsigned long']]);
+const mib = $.NSData.alloc.initWithBase64EncodedStringOptions(${JSON.stringify(mib)}, 0).mutableCopy;
+const size = $.NSData.alloc.initWithBase64EncodedStringOptions(${JSON.stringify(size.toString('base64'))}, 0).mutableCopy;
+const out = $.NSMutableData.dataWithLength(${capacity});
+if ($.sysctl(mib.mutableBytes, 3, out.mutableBytes, size.mutableBytes, null, 0) !== 0)
+  throw new Error('sysctl KERN_PROCARGS2 failed');
+ObjC.unwrap(size.base64EncodedStringWithOptions(0)) + ' ' + ObjC.unwrap(out.base64EncodedStringWithOptions(0));
+`
+  // runner-toolchain-platform: darwin
+  const result = spawnSync('/usr/bin/osascript', ['-l', 'JavaScript', '-e', script], {
+    encoding: 'utf8',
+    maxBuffer: 4 * capacity,
+  })
+  if (result.status !== 0) return null
+  const [length, data] = result.stdout.trim().split(' ')
+  const buffer = Buffer.from(data, 'base64').subarray(
+    0,
+    Number(Buffer.from(length, 'base64').readBigUInt64LE()),
+  )
+  const argc = buffer.readInt32LE(0)
+  let at = buffer.indexOf(0, 4) // end of the executable path
+  while (buffer[at] === 0) at++ // padding before argv[0]
+  const args: string[] = []
+  for (; args.length < argc; at = buffer.indexOf(0, at) + 1)
+    args.push(buffer.toString('utf8', at, buffer.indexOf(0, at)))
+  return args
+}
+
 export async function stopMacDaemonBridge(
   invocation: RnxSelfInvocation,
   target: string | null = macServiceTarget(),
@@ -373,16 +459,9 @@ export async function stopMacDaemonBridge(
   const lock = readDaemonLockfile()
   if (isDaemonLockfileFresh(lock) && lock.pid !== service?.pid) {
     // a lockfile alone cannot authorize a signal after pid reuse.
-    const ownsListener = macBridgeHasListener(lock.pid, lock.bridgePort)
-    const processInfo = spawnSync('ps', ['-o', 'command=', '-p', String(lock.pid)], {
-      encoding: 'utf8',
-    })
-    const command = [invocation.executable, ...invocation.prefixArgs, 'serve'].join(' ')
-    const runningCommand = processInfo.stdout.trim()
     if (
-      !ownsListener ||
-      processInfo.status !== 0 ||
-      (runningCommand !== command && !runningCommand.startsWith(`${command} `))
+      !macBridgeHasListener(lock.pid, lock.bridgePort) ||
+      !macProcessRunsServe(lock.pid, invocation)
     ) {
       throw new Error(
         `cannot hand off bridge on port ${lock.bridgePort}: pid ${lock.pid} is not this Peach invocation`,
@@ -441,7 +520,7 @@ export async function startMacDaemon(
 
 // --- linux bridge ownership --------------------------------------------
 
-// the linux counterparts to the mac listener and command checks above. both
+// the linux counterparts to the mac listener and executable checks above. both
 // read /proc directly instead of shelling out to lsof, ss or ps, so minimal
 // containers and fresh users get the same ownership proof with no extra
 // binaries installed.
@@ -483,16 +562,16 @@ function linuxBridgeHasListener(pid: number, port: number): boolean {
   return false
 }
 
-function readLinuxProcessCommand(pid: number): string | null {
-  // /proc cmdline is the argv vector verbatim; joining with spaces matches
-  // what `ps -o command=` prints without needing procps installed.
+function linuxProcessRunsServe(pid: number, invocation: RnxSelfInvocation): boolean {
+  // /proc/<pid>/exe resolves to the running executable and cmdline is the argv
+  // vector verbatim, so both compare exactly without procps installed.
   try {
-    const args = readFileSync(`/proc/${pid}/cmdline`, 'utf8')
-      .split('\0')
-      .filter((part) => part.length > 0)
-    return args.length > 0 ? args.join(' ') : null
+    const exe = statSync(`/proc/${pid}/exe`, { bigint: true })
+    if (!sameFile(invocation.executable, exe.dev, exe.ino)) return false
+    const args = readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').slice(1)
+    return serveArgs(invocation).every((arg, index) => args[index] === arg)
   } catch {
-    return null
+    return false
   }
 }
 
@@ -514,13 +593,9 @@ export async function stopLinuxDaemonBridge(
   const lock = readDaemonLockfile()
   if (!isDaemonLockfileFresh(lock)) return
   // a lockfile alone cannot authorize a signal after pid reuse.
-  const ownsListener = linuxBridgeHasListener(lock.pid, lock.bridgePort)
-  const runningCommand = readLinuxProcessCommand(lock.pid)
-  const command = [invocation.executable, ...invocation.prefixArgs, 'serve'].join(' ')
   if (
-    !ownsListener ||
-    runningCommand === null ||
-    (runningCommand !== command && !runningCommand.startsWith(`${command} `))
+    !linuxBridgeHasListener(lock.pid, lock.bridgePort) ||
+    !linuxProcessRunsServe(lock.pid, invocation)
   ) {
     throw new Error(
       `cannot hand off bridge on port ${lock.bridgePort}: pid ${lock.pid} is not this Peach invocation`,

package/cli/commands/debug.ts

@@ -40,6 +40,7 @@ import type {
   ImageAuditReport,
   ImageAuditRow,
 } from '../../../peach-engine/src/render-worker/compositor-protocol'
+import type { PeachDebugSnapshotOperation } from '@peach/globals'
 
 interface DebugOptions {
   port?: number
@@ -70,6 +71,7 @@ usage:
 
   record, recent, and clear-events target the tenant; --host selects the page buffer.
   snapshot, snapshots, diff, and clear-snapshots also target the tenant by default.
+  --shell selects the mounted shell worker trees for snapshot operations.
   enable/disable/toggle also update the tenant unless --host is passed.
   shell event buffers are separate; shell console logs are forwarded to the host.
 
@@ -376,7 +378,7 @@ function printImageAudit(
 export async function runDebug(args: string[], opts: DebugOptions) {
   const parsed = parseBridgeCliArgs(args, {
     port: opts.port,
-    stripBooleanFlags: ['--pretty', '--json', '--help', '-h', '--host'],
+    stripBooleanFlags: ['--pretty', '--json', '--help', '-h', '--host', '--shell'],
   })
   const positional = parsed.positional
   const subcommand = positional[0]
@@ -422,6 +424,32 @@ export async function runDebug(args: string[], opts: DebugOptions) {
   const bridge = createBridgeFromParsed(parsed)
 
   try {
+    if (args.includes('--host') && args.includes('--shell')) {
+      throw new Error('select either --host or --shell')
+    }
+    if (
+      !args.includes('--host') &&
+      (sub === 'snapshot' ||
+        sub === 'snapshots' ||
+        sub === 'diff' ||
+        sub === 'clear-snapshots')
+    ) {
+      const operations = {
+        snapshot: 'snapshot',
+        snapshots: 'snapshots',
+        diff: 'diff',
+        'clear-snapshots': 'clearSnapshots',
+      } satisfies Record<string, PeachDebugSnapshotOperation>
+      const result = await callTestBridge(
+        bridge,
+        'debugSnapshot',
+        operations[sub],
+        rest,
+        args.includes('--shell') ? 'shell' : 'tenant',
+      )
+      console.log(fmt(result, pretty))
+      return
+    }
     switch (sub) {
       case 'enable': {
         const channels = parseChannelList(rest[0])