peachsim 0.1.1635 → 0.1.1641

package/cli/commands/upload.ts

@@ -1,6 +1,6 @@
-// peach record upload — capture the currently-loaded bundle + device spec from
-// a running peach sim and POST it to the Contrast upload endpoint. returns a
-// /preview/<id> url that loads this bundle in a frame.
+// peach record upload — publish a recording from a running simulator. scene
+// recordings carry their own content identity; --live-bundle adds the app
+// bundle for interactive playback under the existing bundle identity.
 //
 // uploads with no repository association are private by default: only
 // signed-in members of the uploader's account can open the link until the
@@ -60,6 +60,7 @@ import {
   parseBridgeCliArgs,
 } from '../ws-bridge'
 import type { SootSimTimelineEvent } from '@peach/globals'
+import type { BundleSnapshot } from 'peach-engine/preview/capture-bundle'
 
 interface UploadOptions {
   port?: number
@@ -86,19 +87,6 @@ function parseServerMessage(responseText?: string): string | null {
   }
 }
 
-type BundleSnapshot = {
-  bundleUrl: string | null
-  entry: string | null
-  deviceSpec: InitRequestBody['deviceSpec']
-  runtimeVersion: string | null
-  pageHref: string
-  transformedBundle: {
-    url: string
-    byteLength: number
-    timestamp: number
-  } | null
-}
-
 type AttachedInteractionSnapshot = {
   meta: NonNullable<InitRequestBody['snapshots']>[number] & { id: string }
   bytes: Uint8Array
@@ -184,10 +172,10 @@ export function resolvePublicPreviewOrigin(
 
 function printHelp() {
   console.log(`
-peach record upload — publish the current recorded bundle as a /preview/<id> link
+peach record upload — publish a recording as a /preview/<id> link
 
 usage:
-  peach record upload [--origin <url>] [--public-origin <url>] (--events <path> | --video <path>) [--screenshot <path>] [--owner <org> --repo <repo>] [--sim <sim>] [--open] [--assets-only]
+  peach record upload [--origin <url>] [--public-origin <url>] (--events <path> | --video <path> | --scene <path>) [--live-bundle] [--screenshot <path>] [--owner <org> --repo <repo>] [--sim <sim>] [--open] [--assets-only]
 
 options:
   --origin <url>     upload target (default: ${REMOTE_DEFAULT_ORIGIN})
@@ -210,7 +198,9 @@ options:
                      duration hint for attached flow video
   --scene <path>     a scene recording (.psr.gz) of a remote viewer's display
                      stream. the preview paints it through the simulator's
-                     renderer instead of playing a video
+                     renderer instead of playing a video; uploads without a
+                     live bundle by default
+  --live-bundle     include the running app bundle for Live alongside --scene
   --timeline-events <path>
                      extra trace timeline rows, JSONL or JSONL gz
   --trace-profile <path>
@@ -443,6 +433,12 @@ export async function runUpload(
   const snapshotManifestPath = extractStringFlag(mutableArgs, '--snapshot-manifest')
   const videoPath = extractStringFlag(mutableArgs, '--video')
   const scenePath = extractStringFlag(mutableArgs, '--scene')
+  const includeLiveBundle = extractBoolFlag(mutableArgs, '--live-bundle')
+  if (includeLiveBundle && !scenePath) {
+    console.error('  --live-bundle requires --scene')
+    peachExit(1)
+  }
+  const hasBundle = includeLiveBundle || !scenePath
   const timelineEventsPath = extractStringFlag(mutableArgs, '--timeline-events')
   const traceProfilePath = extractStringFlag(mutableArgs, '--trace-profile')
   const failureBundleDir = extractStringFlag(mutableArgs, '--failure-bundle')
@@ -526,7 +522,7 @@ export async function runUpload(
       bridge,
       '(typeof window.__sootsimCaptureBundle === "function") ? window.__sootsimCaptureBundle() : null',
     )
-    if (snapshot?.bundleUrl) {
+    if (hasBundle && snapshot?.bundleUrl) {
       const bundleOrigin = new URL(snapshot.bundleUrl).origin
       // manifest stays the body-less re-fetch path for bundle-origin static
       // assets (chunks, fonts, wasm). bundle-origin api endpoints would also
@@ -669,7 +665,7 @@ export async function runUpload(
         }
       }
     }
-    if (snapshot?.transformedBundle) {
+    if (hasBundle && snapshot?.transformedBundle) {
       transformedBundleText = await pullTransformedBundle(
         bridge,
         snapshot.transformedBundle.byteLength,
@@ -712,7 +708,7 @@ export async function runUpload(
     )
     peachExit(2)
   }
-  if (!snapshot.bundleUrl) {
+  if (hasBundle && !snapshot.bundleUrl) {
     console.error(
       '  no ?bundle= URL on the current peach tab.\n' +
         '  open the app you want to share first (e.g. peach open 8082), then run upload.',
@@ -725,15 +721,15 @@ export async function runUpload(
   // does not have to re-run sootsim's transforms. fall back to re-fetching
   // the raw metro URL + forcing lazy=false when the transform hasn't
   // published yet (e.g., tab was opened but bundle not finished loading).
-  let bundleBytes: Uint8Array
+  let bundleBytes: Uint8Array | undefined
   let isTransformed = false
-  if (transformedBundleText !== null) {
+  if (hasBundle && transformedBundleText !== null) {
     bundleBytes = new TextEncoder().encode(transformedBundleText)
     isTransformed = true
     console.log(
       `  using post-transform bundle: ${(bundleBytes.byteLength / 1024).toFixed(1)} KiB`,
     )
-  } else {
+  } else if (hasBundle && snapshot.bundleUrl) {
     const fetchBundleUrl = forceInlineBundle(snapshot.bundleUrl)
     if (fetchBundleUrl !== snapshot.bundleUrl) {
       console.log(`  forcing lazy=false for self-contained bundle`)
@@ -788,7 +784,7 @@ export async function runUpload(
     .join('\n')
   const timelineGz = gzipSync(traceTimelineJsonl ? `${traceTimelineJsonl}\n` : '')
   const storageGz =
-    opts.storageSnapshot && hasShareableStorage(opts.storageSnapshot)
+    hasBundle && opts.storageSnapshot && hasShareableStorage(opts.storageSnapshot)
       ? gzipSync(JSON.stringify(opts.storageSnapshot))
       : undefined
   console.log(
@@ -922,7 +918,7 @@ export async function runUpload(
 
   const bundleOrigin = (() => {
     try {
-      return new URL(snapshot.bundleUrl).origin
+      return snapshot.bundleUrl ? new URL(snapshot.bundleUrl).origin : null
     } catch {
       return null
     }
@@ -975,10 +971,9 @@ export async function runUpload(
   // fetcher (same code path as the build's `peach app-fonts stage`) so both
   // pipelines store identical bytes keyed by sha256(url).
   const appFontFiles: PreparedFile[] = []
-  const appFontsWire = await resolveAppFontsWire(
-    appFontsWireFromPageHref(snapshot.pageHref),
-    fetch,
-  )
+  const appFontsWire = hasBundle
+    ? await resolveAppFontsWire(appFontsWireFromPageHref(snapshot.pageHref), fetch)
+    : ''
   if (appFontsWire) {
     const fonts = await fetchAppFontFiles(appFontsWire, {
       onStaged: ({ url, byteLength }) =>
@@ -1007,7 +1002,7 @@ export async function runUpload(
   // still-live metro and persist them keyed by sha256(url). the engine's
   // <img src> resolves them through the share fetch proxy in preview mode.
   const appSplashFiles: PreparedFile[] = []
-  const appSplashWire = appSplashWireFromPageHref(snapshot.pageHref) || ''
+  const appSplashWire = hasBundle ? appSplashWireFromPageHref(snapshot.pageHref) : ''
   if (appSplashWire) {
     const images = await fetchAppSplashImages(appSplashWire, {
       onStaged: ({ url, byteLength }) =>
@@ -1037,8 +1032,9 @@ export async function runUpload(
   // explicitly so the installed app keeps its identity in share replay.
   const appIdentityFiles: PreparedFile[] = []
   let appManifest: string | undefined
-  const metroOrigin = loopbackOriginOf(snapshot.bundleUrl)
-  if (metroOrigin) {
+  const metroOrigin =
+    hasBundle && snapshot.bundleUrl ? loopbackOriginOf(snapshot.bundleUrl) : null
+  if (metroOrigin && snapshot.bundleUrl) {
     const platform = new URL(snapshot.bundleUrl).searchParams.get('platform') || 'ios'
     const manifestUrl = `${metroOrigin}/`
     const response = await fetch(manifestUrl, {
@@ -1120,19 +1116,31 @@ export async function runUpload(
   // brotli source bytes for the upload. finalize verifies the source hash,
   // minifies in the node build container, and stores one canonical brotli
   // bundle. assets stay gzip below.
-  const bundleBr = brotliBundle(bundleBytes)
-  const bundleSha256 = createHash('sha256').update(bundleBytes).digest('hex')
-  console.log(
-    `  bundle raw=${(bundleBytes.byteLength / 1024).toFixed(1)} KiB br=${(bundleBr.byteLength / 1024).toFixed(1)} KiB`,
-  )
+  const bundleBr = bundleBytes ? brotliBundle(bundleBytes) : undefined
+  const identityBytes = bundleBytes ?? sceneBytes
+  if (!identityBytes) throw new Error('upload requires a bundle or scene recording')
+  const contentHash = createHash('sha256').update(identityBytes).digest('hex')
+  if (bundleBytes && bundleBr) {
+    console.log(
+      `  bundle raw=${(bundleBytes.byteLength / 1024).toFixed(1)} KiB br=${(bundleBr.byteLength / 1024).toFixed(1)} KiB`,
+    )
+  }
 
   const initBody: InitRequestBody = {
-    contentHash: bundleSha256,
-    bundleSizeBytes: bundleBytes.byteLength,
-    bundleContentType: guessBundleContentType(snapshot.bundleUrl),
-    bundleEncoding: 'br',
-    bundleMinified: false,
-    bundleOrigin,
+    contentHash,
+    hasBundle,
+    ...(bundleBytes && snapshot.bundleUrl
+      ? {
+          bundleSizeBytes: bundleBytes.byteLength,
+          bundleNativeAppIdentityHeader: snapshot.bundleNativeAppIdentityHeader,
+          bundleContentType: guessBundleContentType(snapshot.bundleUrl),
+          bundleEncoding: 'br',
+          bundleMinified: false,
+          bundleOrigin,
+          entry: snapshot.entry,
+          isTransformed,
+        }
+      : {}),
     runtimeVersion: snapshot.runtimeVersion ?? undefined,
     // config-only fonts resolved by `peach open` and carried on the engine
     // URL. persist them onto the share meta so /preview/<id> re-applies
@@ -1143,8 +1151,6 @@ export async function runUpload(
     // /preview/<id> re-applies `?appSplash=` and paints the same splash; the
     // image bytes are staged above so the engine's <img> resolves in preview.
     appSplash: appSplashWire || undefined,
-    entry: snapshot.entry,
-    isTransformed,
     deviceSpec: snapshot.deviceSpec,
     installationId: gitHubIdentity?.installationId ?? undefined,
     repoId: gitHubIdentity?.repoId,
@@ -1227,7 +1233,7 @@ export async function runUpload(
   }
 
   const putT0 = Date.now()
-  let putBytes = bundleBr.byteLength
+  let putBytes = bundleBr?.byteLength ?? 0
   for (const f of prepared) putBytes += f.bytes.byteLength
   if (eventsGz) putBytes += eventsGz.byteLength
   putBytes += timelineGz.byteLength
@@ -1263,7 +1269,7 @@ export async function runUpload(
     })
     finalize = result.finalize
     const totalObjects =
-      1 +
+      (result.init.bundle ? 1 : 0) +
       result.init.files.length +
       (result.init.events ? 1 : 0) +
       (result.init.timeline ? 1 : 0) +

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

@@ -22,6 +22,7 @@ import {
   softwareChromeLaunchOptions,
 } from '../../../../scripts/lib/reap-browser'
 import { createBrowserPageTargetReader } from '../../../peach-engine/src/browser-page-target'
+import { captureBrowserAccessibility } from '../../../peach-engine/src/capture/browser-accessibility-host'
 import {
   readBrowserCompositeCaptureRequest,
   resolveBrowserCompositeCdpClip,
@@ -108,10 +109,10 @@ const viewportSpec = /^(\\d+)x(\\d+)$/.exec(process.env.SOOTSIM_PW_VIEWPORT || '
 const viewport = viewportSpec
   ? { width: Number(viewportSpec[1]), height: Number(viewportSpec[2]) }
   : { width: 600, height: 900 };
-// device pixels per css pixel. playwright's default is 1, which makes the
-// engine allocate its canvas backing store at HALF the resolution a normal
-// retina-mac chrome would (dpr 2) — the sim looks visibly soft. default to 2
-// so a driver-launched sim matches what the user sees in their own browser.
+// host display pixels per css pixel; default to a retina Mac browser's 2.
+// medium renders at 2 and high at device native, independently of browser DPR.
+// low follows measured on-screen density, capped at device native.
+// SOOTSIM_PW_DSF changes browser DPR, not the selected render resolution.
 const deviceScaleFactor = Number(process.env.SOOTSIM_PW_DSF || 2);
 const closeTimeoutMs = Number(process.env.SOOTSIM_PW_CLOSE_TIMEOUT_MS || 2500);
 const connectAckFile = process.env.SOOTSIM_PW_CONNECTED_ACK_FILE || '';
@@ -126,6 +127,7 @@ const listProcessChildren = ${listProcessChildren.toString()};
 const { tmpdir } = require('os');
 const { join } = require('path');
 const createBrowserPointerDispatcher = ${createBrowserPointerDispatcher.toString()};
+const captureBrowserAccessibility = ${captureBrowserAccessibility.toString()};
 const automateWebViewFrames = ${automateWebViewFrames.toString()};
 const automateWebAuthenticationSessions = ${automateWebAuthenticationSessions.toString()};
 const webViewAutomationHelpers = ${webViewAutomationHelpersSource()};
@@ -143,12 +145,9 @@ const readChromiumQueue = ${readChromiumQueue.toString()};
 // aborted/closed \`peach open\` leaked a renderer + gpu helper burning 100%+
 // CPU until manually killed (multiple incidents 2026-06).
 //
-// fix: identify our chrome tree by its UNIQUE user-data-dir. every helper a
-// chrome root spawns inherits \`--user-data-dir=<dir>\` in its cmdline, so
-// \`pgrep -f <profileDir>\` finds exactly the tree we launched and nothing else
-// — Chrome for Testing and bundled playwright chromium alike. as a side benefit we
-// no longer need the launch / launchPersistentContext fork: we ALWAYS use a
-// profile dir (mkdtemp'd if the caller didn't pass one, then removed at exit).
+// a named profile can already belong to another host. its path finds browser
+// candidates; the unique launch environment proves which ones we may reap,
+// including helpers reparented after the browser root exits.
 const reapEnabled = process.platform !== 'win32';
 let profileDir = callerUserDataDir;
 let ephemeralProfile = false;
@@ -160,33 +159,35 @@ if (!profileDir) {
 // host a bounded temporary cache so persistent named profiles retain cookies
 // and storage without multiplying a private cache for every profile.
 const diskCacheDir = mkdtempSync(join(tmpdir(), 'peach-playwright-cache-'));
-const chromePidsByProfile = () => {
+let profileLaunched = false;
+// [pid, command line] for every process on the profile. linux reads /proc,
+// since minimal and rootless images ship no ps.
+const profileProcesses = () => {
   if (!reapEnabled) return [];
   try {
     // match the whole --user-data-dir argument: a pattern search also found
     // browsers whose profile path merely starts with this one.
     const flag = ' --user-data-dir=' + profileDir + ' ';
-    return execSync('ps -axo pid=,command=', {
-      stdio: ['ignore', 'pipe', 'ignore'],
-      maxBuffer: Infinity,
-    })
-      .toString().split('\\n').map((line) => line.trim().match(/^(\\d+)\\s+(.*)$/))
-      .filter((row) => row && (' ' + row[2] + ' ').includes(flag))
-      .map((row) => Number(row[1]))
-      .filter((p) => p && p !== process.pid);
-  } catch { return []; }
-};
-const chromeCommandsByProfile = () => {
-  if (!reapEnabled) return [];
-  const pids = chromePidsByProfile();
-  if (pids.length === 0) return [];
-  try {
-    return execSync('ps -p ' + pids.join(',') + ' -o command=', {
-      stdio: ['ignore', 'pipe', 'ignore'],
-      maxBuffer: Infinity,
-    }).toString().split('\\n').filter(Boolean);
-  } catch { return []; }
+    const rows = process.platform === 'linux'
+      ? readdirSync('/proc').filter((name) => /^\\d+$/.test(name)).map((name) => {
+          let command = '';
+          // a process can exit between the listing and this read
+          try { command = readFileSync('/proc/' + name + '/cmdline', 'utf8').split('\\0').join(' ').trim(); } catch {}
+          return [Number(name), command];
+        })
+      : execSync('ps -axo pid=,command=', {
+          stdio: ['ignore', 'pipe', 'ignore'],
+          maxBuffer: Infinity,
+        })
+          .toString().split('\\n').map((line) => line.trim().match(/^(\\d+)\\s+(.*)$/))
+          .filter(Boolean).map((row) => [Number(row[1]), row[2]]);
+    return rows.filter(([pid, command]) => pid && pid !== process.pid && (' ' + command + ' ').includes(flag));
+  } catch (error) {
+    throw new Error('[playwright-driver] cannot establish browser profile ownership: ' + String(error));
+  }
 };
+const chromePidsByProfile = () => profileProcesses().map(([pid]) => pid);
+const chromeCommandsByProfile = () => profileProcesses().map(([, command]) => command);
 const assertNoUnsafeSwiftShaderFlag = () => {
   if (!hardwareGpuRequired) return;
   const unsafe = chromeCommandsByProfile().find((command) =>
@@ -207,7 +208,29 @@ const killTree = (pid) => {
   for (const k of kids) killTree(k);
   try { process.kill(pid, 'SIGKILL'); } catch {}
 };
-const reapChrome = () => { for (const pid of chromePidsByProfile()) killTree(pid); };
+const reapChrome = () => {
+  try {
+    for (const pid of chromePidsByProfile()) {
+      let owned = false;
+      if (process.platform === 'linux') {
+        try {
+          owned = readFileSync('/proc/' + pid + '/environ', 'utf8').split('\\0')
+            .includes('PEACH_PW_BROWSER_OWNER=' + diskCacheDir);
+        } catch {}
+      } else {
+        const plain = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
+        const withEnv = spawnSync('ps', ['eww', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
+        const argv = (plain.stdout || '').trimEnd();
+        const full = (withEnv.stdout || '').trimEnd();
+        owned = plain.status === 0 && withEnv.status === 0 && full.startsWith(argv) &&
+          (full.slice(argv.length) + ' ').includes(' PEACH_PW_BROWSER_OWNER=' + diskCacheDir + ' ');
+      }
+      if (owned) killTree(pid);
+    }
+  } catch (error) {
+    process.stderr.write('[playwright-driver] browser teardown refused: ' + String(error) + '\\n');
+  }
+};
 const removeDisposableCaches = (root) => {
   let children = [];
   try { children = readdirSync(root, { withFileTypes: true }); } catch { return; }
@@ -237,7 +260,7 @@ const cleanupProfile = () => {
     try { rmSync(profileDir, { recursive: true, force: true }); } catch {}
     return;
   }
-  removeDisposableCaches(profileDir);
+  if (profileLaunched) removeDisposableCaches(profileDir);
 };
 (async () => {
   const pw = require(modulePath);
@@ -401,9 +424,8 @@ const cleanupProfile = () => {
     await bounded('desktop host stop', stopDesktopHost, timeoutMs);
     if (context) await bounded('context.close', () => context.close(), timeoutMs);
     await terminateBrowserProcess();
-    // close() + root-SIGKILL above handle the graceful case; the helper tree
-    // (gpu/renderer/utilities) reparents and survives every one of those, so
-    // we always sweep by our unique profile dir as the load-bearing teardown.
+    // close() can leave reparented helpers; reap only this launch's browser
+    // and helpers, even if another host now uses the same named profile.
     reapChrome();
     cleanupProfile();
     if (connectAckFile) {
@@ -494,10 +516,11 @@ const cleanupProfile = () => {
     const opts = channel
       ? { headless, channel, viewport, deviceScaleFactor }
       : { headless, viewport, deviceScaleFactor };
+    opts.env = { ...process.env, PEACH_PW_BROWSER_OWNER: diskCacheDir };
     opts.executablePath = executablePath;
     if (libraryPath) {
       opts.env = {
-        ...process.env,
+        ...opts.env,
         LD_LIBRARY_PATH: [libraryPath, process.env.LD_LIBRARY_PATH].filter(Boolean).join(':'),
       };
     }
@@ -561,11 +584,9 @@ const cleanupProfile = () => {
     // room for chrome's own toolbar, so the window isn't desktop-shaped
     // around a letterboxed page.
     if (!headless) opts.args.push('--window-size=' + viewport.width + ',' + (viewport.height + 88));
-    // ALWAYS persistent: every chrome process inherits --user-data-dir=<dir>
-    // in its cmdline, which is how reapChrome() finds the whole tree (root +
-    // helpers) on shutdown. without a unique dir there is no way to attribute
-    // an orphaned helper back to us, which is the leak we just fixed.
-    return await pw.chromium.launchPersistentContext(profileDir, opts);
+    const launched = await pw.chromium.launchPersistentContext(profileDir, opts);
+    profileLaunched = true;
+    return launched;
   };
   // the host-wide chromium slot is held for this host's life; its exit frees it
   await acquireChromiumAdmission({
@@ -663,6 +684,8 @@ const cleanupProfile = () => {
     await shutdown(0);
   });
   const pointerHosts = new WeakMap();
+  await context.exposeBinding('__peachHostAccessibility', (source, instanceIds) =>
+    captureBrowserAccessibility(source.page, instanceIds));
   await context.exposeBinding('__sootsimHostPointer', async (source, value) => {
     let pending = pointerHosts.get(source.page);
     if (!pending) {

package/cli/flow-live-status.ts

@@ -13,8 +13,6 @@ export type LiveStepStatus = 'running' | 'success' | 'failure' | 'skipped'
 
 type PlanStep = { index: number; name: string; target?: string }
 
-const PAUSE_POLL_MS = 400
-
 function replyPaused(reply: unknown) {
   if (typeof reply !== 'object' || reply == null || !('control' in reply)) return false
   const control = reply.control

package/cli/main.ts

@@ -42,7 +42,7 @@ async function handleTopLevelError(err: unknown): Promise<never> {
   // peach's known top-level errors are all single-line, narrow strings.
   // everything else gets the full stack so unexpected crashes still surface.
   const isKnownCliFailure =
-    /^command timed out after \d+s$/.test(msg) ||
+    /^command timed out after \d+(?:\.\d+)?s$/.test(msg) ||
     /^cannot hand off bridge on port \d+: pid \d+ is not this Peach invocation$/.test(
       msg,
     ) ||
@@ -466,7 +466,7 @@ try {
         // inner verb's --json payload, so it never needs the shared bridge
         // machinery that lives inside runInspect.
         const { runAssert } = await import('./commands/assert')
-        await runAssert(parsed.commandArgs)
+        await runAssert(parsed.commandArgs, { port, sim: globalSimTarget })
         break
       }
 

package/cli/outbound-endpoints.ts

@@ -528,6 +528,8 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     category: 'guest_app_network',
     count: 1,
   },
+  "packages/peach-engine/src/mcp/shared-config-transport.ts :: fetch :: '/__sootsim/shared-config'":
+    { category: 'same_origin_runtime', count: 1 },
   'packages/peach-engine/src/mcp/ws-bridge.ts :: fetch :: bridgeHealthUrl': {
     category: 'local_development',
     count: 1,
@@ -561,8 +563,6 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     category: 'guest_app_network',
     count: 1,
   },
-  "packages/peach-engine/src/projects/projects-persistence.ts :: fetch :: '/__sootsim/shared-config'":
-    { category: 'same_origin_runtime', count: 1 },
   'packages/peach-engine/src/react-native/index.ts :: fetch :: resource': {
     category: 'guest_app_network',
     count: 1,
@@ -655,7 +655,7 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     count: 1,
   },
   "packages/peach-engine/src/settings/persistence.ts :: fetch :: '/__sootsim/shared-config'":
-    { category: 'same_origin_runtime', count: 2 },
+    { category: 'same_origin_runtime', count: 1 },
   'packages/peachsim/cli/app-fonts.ts :: fetch :: `${origin}/`': {
     category: 'local_development',
     count: 1,
@@ -867,8 +867,10 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     category: 'same_origin_runtime',
     count: 1,
   },
-  'packages/peach-engine/src/engine/image-loader.ts :: fetch-alias :: resolveImageFetchUri(uri)':
-    { category: 'guest_app_network', count: 1 },
+  'packages/peach-engine/src/engine/image-loader.ts :: fetch-alias :: uri': {
+    category: 'guest_app_network',
+    count: 1,
+  },
   'packages/peach-engine/src/ExternalApp.tsx :: fetch-alias :: requestUrl': {
     category: 'guest_app_network',
     count: 1,

package/cli/pause-aware-timeout.ts

@@ -98,5 +98,9 @@ export function setPauseAwareTimeout(
   }
   return () => {
     timers.delete(timer)
+    if (timers.size === 0 && poll) {
+      clearInterval(poll)
+      poll = undefined
+    }
   }
 }

package/cli/ws-bridge.ts

@@ -333,9 +333,11 @@ export function printBridgeWorldNotice(
 export interface WsBridge {
   readonly plane?: 'local' | 'cloud'
   // `opts.timeoutMs` overrides the bridge-wide commandTimeoutMs for a single
-  // call — used for fast readiness probes so a dead/unresponsive sim fails in
-  // seconds instead of stalling the full command timeout.
-  send(cmd: WsBridgeCommand, opts?: { timeoutMs?: number }): Promise<any>
+  // call. defaultTimeoutMs supplies a probe cap unless --timeout was explicit.
+  send(
+    cmd: WsBridgeCommand,
+    opts?: { timeoutMs?: number; defaultTimeoutMs?: number },
+  ): Promise<any>
   // includeRetained appends the bridge's retained disconnected sims
   // (readyState 'closed' with disconnectCause) after the live ones. only
   // loss-reporting surfaces pass it; every other consumer keeps the
@@ -372,15 +374,10 @@ export class BridgeSimLockedError extends Error {
   }
 }
 
-interface WsResponse {
-  id: number
-  result?: any
-  error?: string
-}
-
 interface WsBridgeOptions {
   connectTimeoutMs?: number
   commandTimeoutMs?: number
+  explicitTimeout?: boolean
   simId?: string
   cliLabel?: string
   leaseScope?: 'connection'
@@ -455,12 +452,14 @@ export interface ParsedBridgeCliArgs {
   simId?: string
   simIdSource: 'flag' | 'saved' | 'none'
   commandTimeoutMs: number
+  explicitTimeout?: boolean
 }
 
 interface BridgeFlagState {
   wsPort: number
   explicitPort: boolean
   commandTimeoutMs: number
+  explicitTimeout?: boolean
   simId: string | undefined
   simIdSource: ParsedBridgeCliArgs['simIdSource']
 }
@@ -487,7 +486,10 @@ const BRIDGE_VALUE_FLAGS_TABLE: readonly {
   {
     names: ['--timeout'],
     apply: (state, value) => {
-      if (value !== undefined) state.commandTimeoutMs = Number(value)
+      if (value !== undefined) {
+        state.commandTimeoutMs = Number(value)
+        state.explicitTimeout = true
+      }
     },
   },
   {
@@ -573,6 +575,7 @@ export function parseBridgeCliArgs(
     simId: state.simId,
     simIdSource: state.simIdSource,
     commandTimeoutMs: state.commandTimeoutMs,
+    explicitTimeout: state.explicitTimeout,
   }
 }
 
@@ -749,7 +752,10 @@ export function createBridge(wsPort: number, opts: WsBridgeOptions = {}): WsBrid
     async send(cmd, callOpts) {
       // NOTE: `opts` (the createBridge closure arg) carries simId; do not
       // shadow it with the per-call arg.
-      const effectiveTimeoutMs = callOpts?.timeoutMs ?? commandTimeoutMs
+      const effectiveTimeoutMs =
+        callOpts?.timeoutMs ??
+        (opts.explicitTimeout ? commandTimeoutMs : callOpts?.defaultTimeoutMs) ??
+        commandTimeoutMs
       const sendOnce = async (
         defaultSimId?: string,
         cmdOverride?: Record<string, any>,
@@ -766,11 +772,7 @@ export function createBridge(wsPort: number, opts: WsBridgeOptions = {}): WsBrid
           const clearTimeoutFn = setPauseAwareTimeout(
             () => {
               pending.delete(id)
-              reject(
-                new Error(
-                  `command timed out after ${Math.round(effectiveTimeoutMs / 1000)}s`,
-                ),
-              )
+              reject(new Error(`command timed out after ${effectiveTimeoutMs / 1000}s`))
             },
             effectiveTimeoutMs,
             lineageBySimId.get(payload.simId)?.hostPid,
@@ -955,6 +957,7 @@ export function createBridgeFromParsed(parsed: ParsedBridgeCliArgs): WsBridge {
   if (cloudBridge) return cloudBridge
   const options = {
     commandTimeoutMs: parsed.commandTimeoutMs,
+    explicitTimeout: parsed.explicitTimeout,
     simId: parsed.simId,
     simIdSource: parsed.simIdSource,
   }