peachsim 0.1.1620 → 0.1.1635

package/cli/maestro-accessibility.ts

@@ -0,0 +1,53 @@
+import type { PeachAccessibilityNode } from '@peach/globals'
+
+// maestro reads ios frames as integer edges (AXElement.boundsString).
+export function accessibilityBounds(node: Pick<PeachAccessibilityNode, 'frame'>): {
+  x: number
+  y: number
+  width: number
+  height: number
+} {
+  const left = Math.trunc(node.frame.x)
+  const top = Math.trunc(node.frame.y)
+  return {
+    x: left,
+    y: top,
+    width: Math.trunc(node.frame.x + node.frame.width) - left,
+    height: Math.trunc(node.frame.y + node.frame.height) - top,
+  }
+}
+
+// upstream Filters.containsChild compares the resolved child TreeNode against
+// a candidate's immediate children by structural equality: the native
+// attribute map, the boolean flags, and the children, recursively. the native
+// hintText attribute is the placeholder (accessibilityHint is not a TreeNode
+// attribute), and engine identity (elementId/nodeId) plus the projection's own
+// metadata (type, role, isAccessibilityElement, state) are not part of that
+// native shape.
+// bounds is explicit so serialized page evaluation survives cli minification.
+export function sameNativeAccessibilityShape(
+  a: PeachAccessibilityNode,
+  b: PeachAccessibilityNode,
+  bounds: typeof accessibilityBounds,
+): boolean {
+  if (
+    (a.testID ?? '') !== (b.testID ?? '') ||
+    (a.label ?? '') !== (b.label ?? '') ||
+    (a.placeholder ?? '') !== (b.placeholder ?? '') ||
+    (a.value ?? '') !== (b.value ?? '') ||
+    a.enabled !== b.enabled ||
+    a.selected !== b.selected ||
+    a.checked !== b.checked ||
+    a.clickable !== b.clickable ||
+    (a.hasFocus ?? false) !== (b.hasFocus ?? false) ||
+    JSON.stringify(bounds(a)) !== JSON.stringify(bounds(b)) ||
+    a.children.length !== b.children.length
+  ) {
+    return false
+  }
+  for (const [index, child] of a.children.entries()) {
+    const other = b.children[index]
+    if (!other || !sameNativeAccessibilityShape(child, other, bounds)) return false
+  }
+  return true
+}

package/cli/maestro-compare.ts

@@ -121,8 +121,8 @@ function absolutizeRefs(steps: unknown, flowDir: string): unknown {
   })
 }
 
-// insert one capture after every screen-changing top-level step. subflows run
-// as one step and are captured once, after they return.
+// insert maestro's pixel-stillness wait before each checkpoint on both sides.
+// subflows run as one step and are captured once, after they return.
 export function instrumentFlowSource(
   source: string,
   flowDir: string,
@@ -159,6 +159,7 @@ export function instrumentFlowSource(
     const label = stepLabel(step)
     const name = `${COMPARE_SHOT_DIR}/${String(captures.length + 1).padStart(3, '0')}-${slugify(label)}`
     captures.push({ name, step: index + 1, label })
+    out.push('waitForAnimationToEnd')
     out.push({ takeScreenshot: name })
   }
   // maestro reads flows as yaml 1.1, where a bare yes, no, on or off is a
@@ -280,14 +281,52 @@ export function nativeStepsFromCommandsJson(json: unknown): CompareStep[] {
   return steps
 }
 
-export function nativeFlowFailureFromLog(log: string, name: string): string | undefined {
-  const verdict = `[Failed] ${name}`
-  return log.split(/[\r\n]+/).some((line) => {
-    const text = line.trim()
-    return text === verdict || text.startsWith(`${verdict} (`)
+const XML_ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+}
+
+function decodeXml(text: string): string {
+  return text.replace(/&(?:#(\d+)|#x([\da-f]+)|(\w+));/gi, (match, dec, hex, name) => {
+    if (dec || hex) return String.fromCodePoint(parseInt(dec ?? hex, dec ? 10 : 16))
+    return XML_ENTITIES[name] ?? match
   })
-    ? 'Maestro reported this flow failed; see ios.log'
-    : undefined
+}
+
+export function junitFlowKey(name: string, fileStem: string): string {
+  return JSON.stringify([name, fileStem])
+}
+
+// maestro's own per-flow report (--format junit): one testcase per flow, whose
+// status and failure text are the verdict whatever the flow did or printed.
+// values hold the failure message per testcase, undefined for a pass, in
+// report order so flows that share a name and file stem pair in run order.
+export function nativeFlowVerdictsFromJunit(
+  xml: string,
+): Map<string, Array<string | undefined>> {
+  const verdicts = new Map<string, Array<string | undefined>>()
+  for (const match of xml.matchAll(/<testcase\b([^>]*?)(\/>|>([\s\S]*?)<\/testcase>)/g)) {
+    const attrs = new Map<string, string>()
+    for (const attr of (match[1] ?? '').matchAll(/([\w:-]+)="([^"]*)"/g)) {
+      attrs.set(attr[1]!, decodeXml(attr[2]!))
+    }
+    const file = attrs.get('file')
+    const name = attrs.get('name')
+    if (file === undefined || name === undefined) continue
+    const body = match[3] ?? ''
+    const failure =
+      /<(?:failure|error)\b[^>]*?(?:\/>|>([\s\S]*?)<\/(?:failure|error)>)/.exec(body)
+    const failed = failure !== null || attrs.get('status') === 'ERROR'
+    const message = failure?.[1] ? decodeXml(failure[1]).trim() : ''
+    const key = junitFlowKey(name, path.basename(file).replace(/\.(ya?ml)$/i, ''))
+    const list = verdicts.get(key) ?? []
+    list.push(failed ? `Maestro failed this flow: ${message || 'no message'}` : undefined)
+    verdicts.set(key, list)
+  }
+  return verdicts
 }
 
 // peach's commands.json (maestro-report.ts buildFlowCommandsJson)
@@ -325,6 +364,30 @@ export interface ScreenDiff {
   maskedTopPx: number
 }
 
+// captures of one framebuffer can differ by a column or row: maestro's xctest
+// shot drops the rightmost column of an odd framebuffer. such a pair is scored
+// on the top-left area both have, with no resampling, which would shift every
+// edge. null when the sizes match or differ by more than one pixel.
+export function commonAreaSize(
+  a: { width: number; height: number },
+  b: { width: number; height: number },
+): { width: number; height: number } | null {
+  const dw = Math.abs(a.width - b.width)
+  const dh = Math.abs(a.height - b.height)
+  if ((dw === 0 && dh === 0) || dw > 1 || dh > 1) return null
+  return { width: Math.min(a.width, b.width), height: Math.min(a.height, b.height) }
+}
+
+function cropTopLeft(src: PNG, width: number, height: number): PNG {
+  if (src.width === width && src.height === height) return src
+  const out = new PNG({ width, height })
+  for (let y = 0; y < height; y++) {
+    const from = y * src.width * 4
+    src.data.copy(out.data, y * width * 4, from, from + width * 4)
+  }
+  return out
+}
+
 function resample(src: PNG, width: number, height: number): PNG {
   const out = new PNG({ width, height })
   const sx = src.width / width
@@ -402,8 +465,13 @@ export function compareScreens(
   peachPng: Buffer,
   opts: { maskTopPx?: number } = {},
 ): { diff: ScreenDiff; triptych: Buffer } {
-  const native = PNG.sync.read(nativePng)
+  let native: PNG = PNG.sync.read(nativePng)
   let peach: PNG = PNG.sync.read(peachPng)
+  const common = commonAreaSize(native, peach)
+  if (common) {
+    native = cropTopLeft(native, common.width, common.height)
+    peach = cropTopLeft(peach, common.width, common.height)
+  }
   const { width, height } = native
   const aspectMismatch = Math.abs(peach.width / peach.height - width / height) > 0.01
   const resized = peach.width !== width || peach.height !== height
@@ -455,6 +523,30 @@ export interface CompareSide {
   errors: string[]
 }
 
+// flow verdicts own status; diagnostics do not reject a pass.
+export function buildCompareSide(
+  steps: CompareStep[],
+  outcome: CompareSide['status'],
+  extraErrors: string[],
+  runFailure?: string,
+): CompareSide {
+  const failed = steps.find((step) => step.status === 'failed')
+  const executed = steps.some((step) => step.status !== 'skipped')
+  const errors = [
+    ...(failed ? [`step "${failed.label}" failed: ${failed.error ?? 'no message'}`] : []),
+    ...(runFailure ? [runFailure] : []),
+    ...extraErrors,
+    ...(!executed && outcome !== 'not run' ? ['flow executed no steps'] : []),
+  ]
+  return {
+    status:
+      outcome === 'passed' && (failed || runFailure || !executed) ? 'failed' : outcome,
+    durationMs: steps.reduce((sum, step) => sum + step.durationMs, 0),
+    steps,
+    errors,
+  }
+}
+
 export interface CompareScreen {
   name: string
   step: number
@@ -578,10 +670,14 @@ function screenCard(screen: CompareScreen, threshold: number, flowIndex: number)
   ].filter(Boolean)
   let body = ''
   if (screen.image) {
+    const imageUrl = screen.image.split('/').map(encodeURIComponent).join('/')
     body = `<div class="cols"><span>iOS simulator</span><span>Peach</span><span>pixel diff</span></div>
-<a href="${esc(screen.image)}" target="_blank"><img loading="lazy" src="${esc(screen.image)}" alt="${esc(screen.label)}"></a>`
+<a href="${esc(imageUrl)}" target="_blank"><img loading="lazy" src="${esc(imageUrl)}" alt="${esc(screen.label)}"></a>`
   } else {
-    const only = screen.nativeOnly ?? screen.peachOnly
+    const only = (screen.nativeOnly ?? screen.peachOnly)
+      ?.split('/')
+      .map(encodeURIComponent)
+      .join('/')
     body = only
       ? `<div class="cols one"><span>${screen.nativeOnly ? 'iOS simulator' : 'Peach'} only</span></div><a href="${esc(only)}" target="_blank"><img class="single" loading="lazy" src="${esc(only)}" alt="${esc(screen.label)}"></a>`
       : '<p class="quiet">Neither side reached this step.</p>'

package/cli/main.ts

@@ -63,7 +63,8 @@ async function handleTopLevelError(err: unknown): Promise<never> {
     msg.startsWith(
       `package.json already defines scripts.${rnxPublicBrand.commandName} as `,
     ) ||
-    msg.startsWith('could not resolve a native bundle for ')
+    msg.startsWith('could not resolve a native bundle for ') ||
+    msg.startsWith('could not load ')
   if (isKnownCliFailure && !process.env.SOOTSIM_VERBOSE) {
     process.stderr.write(`  ${msg}\n`)
     await exitWithFlushedOutput(1)

package/cli/outbound-endpoints.ts

@@ -147,7 +147,8 @@ export const OUTBOUND_ENDPOINTS: Record<string, OutboundEndpointDeclaration> = {
   },
   remote_display_server: {
     category: 'explicit-user-action',
-    destination: 'display-server WebSocket URL configured by the embedding host',
+    destination:
+      'display-server WebSocket URL, or scene recording URL, configured by the embedding host',
     preConsent: true,
     payload:
       'display protocol identity, local input events, scroll lifecycle, resync requests, and applied/painted acknowledgements',
@@ -159,13 +160,11 @@ export const OUTBOUND_ENDPOINTS: Record<string, OutboundEndpointDeclaration> = {
     payload: 'preview objects selected by the user for upload',
   },
   // its own entry, deliberately not folded into contrast_user_action. this is
-  // the only egress that sends the CONTENTS of the user's project somewhere,
-  // and to an operator-chosen host rather than a Contrast one, so it must not
-  // be readable as "the usual Contrast call".
+  // the egress that sends the contents of the user's project to a cloud host.
   peach_cloud_box: {
     category: 'explicit-user-action',
     destination:
-      'the Peach Cloud box service named by --endpoint or PEACH_BOX_ENDPOINT; no default, so this call cannot happen unless the user names a host',
+      'the deployed Peach Cloud box service by default, overridden by --endpoint or PEACH_BOX_ENDPOINT',
     preConsent: false,
     payload:
       'every file git reports for the current checkout, then shell commands and file reads and writes for as long as the box shell is open',
@@ -252,6 +251,10 @@ export interface OutboundCallDeclaration {
 // a new fetch, websocket, node HTTP request, or TCP connection has no entry and
 // fails scripts/check/outbound-endpoints.ts until its destination and consent behavior are declared.
 export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> = {
+  'packages/peach-engine/src/launch-metadata.ts :: fetch :: reference': {
+    category: 'local_development',
+    count: 1,
+  },
   'packages/peach-engine/src/engine/barcode-reader.worker.ts :: fetch :: wasmUrl': {
     category: 'same_origin_runtime',
     count: 1,
@@ -282,6 +285,10 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
   // empty, so the request carries no project or app data.
   'packages/peachsim/cli/cloud-client.ts :: fetch :: `${options.apiOrigin}/v1/boxes/${encodeURIComponent()}/display-grant`':
     { category: 'peach_cloud_sim', count: 1 },
+  // a fresh box's boot receipts are read until its page loads or reports an
+  // error; the request carries no body.
+  'packages/peachsim/cli/cloud-client.ts :: fetch :: `${options.apiOrigin}/v1/boxes/${encodeURIComponent()}/lifecycle`':
+    { category: 'peach_cloud_sim', count: 1 },
   // `peach remote` creates through the instance api and lists what it made.
   // the create carries labels and wait=true in the query; the list filters
   // by the remote label.
@@ -379,6 +386,8 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
   'packages/peach-cloud-box/src/browser-run.ts :: fetch :: `https://browser.invalid/v1/devtools/browser/${sessionId}`':
     { category: 'peach_cloud_box', count: 2 },
   // list the account sessions a cloud box is billed against. no project content.
+  "packages/peachsim/cli/remote-simulators.ts :: fetch :: `${account.apiOrigin.replace(/\\/+$/, '')}/api/v1/rnx/sessions?${query}`":
+    { category: 'contrast_user_action', count: 1 },
   "packages/peach-cloud-box/src/client.ts :: fetch :: `${options.apiOrigin.replace(/\\/+$/, '')}/api/v1/rnx/sessions?${search}`":
     { category: 'contrast_user_action', count: 1 },
   // `peach box connect` asks the account service which box that ID or name is
@@ -482,7 +491,7 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
   },
   'packages/peach-engine/src/engine/lottie-runtime.ts :: fetch :: descriptor.value': {
     category: 'guest_app_network',
-    count: 2,
+    count: 1,
   },
   'packages/peach-engine/src/bundle-fetch.ts :: fetch-alias :: buildBrowserAssetProxyUrl(devServerUrl)':
     { category: 'guest_app_network', count: 1 },
@@ -525,6 +534,8 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
   },
   'packages/peach-engine/src/mcp/ws-bridge.ts :: websocket :: resolveSootsimBridgeWebSocketUrl({ bridgePort, href: window.location.href, })':
     { category: 'local_development', count: 1 },
+  'packages/peach-engine/src/remote-stream/browser-tenant-proxy.ts :: fetch :: this.config.url':
+    { category: 'remote_display_server', count: 1 },
   'packages/peach-engine/src/remote-stream/browser-tenant-proxy.ts :: websocket :: this.config.url':
     { category: 'remote_display_server', count: 1 },
   'packages/peach-engine/src/menu/menuActions.ts :: fetch :: screenshot': {
@@ -612,6 +623,10 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     category: 'guest_app_network',
     count: 1,
   },
+  'packages/peach-engine/src/render-worker/map-host.ts :: fetch-alias :: request.url': {
+    category: 'guest_app_network',
+    count: 1,
+  },
   'packages/peach-engine/src/render-worker/map-host.ts :: fetch-alias :: url': {
     category: 'map_style_delivery',
     count: 1,
@@ -658,6 +673,14 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
       category: 'local_development',
       count: 1,
     },
+  'packages/peachsim/cli/commands/control.ts :: net.connect :: port': {
+    category: 'local_development',
+    count: 1,
+  },
+  'packages/peachsim/cli/commands/control.ts :: fetch :: origin': {
+    category: 'local_development',
+    count: 1,
+  },
   'packages/peachsim/cli/commands/control.ts :: websocket :: `ws://127.0.0.1:${port}`': {
     category: 'local_development',
     count: 1,
@@ -764,6 +787,8 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     category: 'local_development',
     count: 1,
   },
+  'packages/peach-engine/src/components/native-ui/ShareSheetView.tsx :: fetch-alias :: `/__fetch-proxy?url=${encodeURIComponent()}`':
+    { category: 'guest_app_network', count: 1 },
   'packages/peachsim/src/dev-bundle-resolution.ts :: fetch :: `/__fetch-proxy?url=${encodeURIComponent()}`':
     { category: 'guest_app_network', count: 1 },
   'packages/peachsim/src/dev-bundle-resolution.ts :: fetch :: targetUrl': {
@@ -788,6 +813,10 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     category: 'local_development',
     count: 1,
   },
+  'packages/peachsim/src/expo-swift-ready.ts :: fetch :: endpointUrl': {
+    category: 'local_development',
+    count: 1,
+  },
   'packages/peach-engine/src/expo-swift-compilation.ts :: fetch-alias :: address': {
     category: 'local_development',
     count: 1,

package/cli/parent-pid.ts

@@ -68,15 +68,6 @@ function buildComm(): CommLookup {
 }
 
 function build(): Lookup {
-  // on any platform, if the shell exports $PPID and it differs from the
-  // node-level process.ppid, it's the shell's own parent — one level up
-  // from where we need to be. this is the cheapest and most portable
-  // grand-ppid source since it needs no subprocess or FFI.
-  const envPpid = Number(process.env.PPID)
-  if (Number.isFinite(envPpid) && envPpid > 1 && envPpid !== process.ppid) {
-    return () => envPpid
-  }
-
   if (process.platform === 'linux') return buildLinux()
   if (process.platform === 'darwin') {
     // on Bun: libproc via FFI is ~0.8µs/call. on Node: one `ps` snapshot of

package/cli/pause-aware-timeout.ts

@@ -0,0 +1,102 @@
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+// the team machine load governor SIGSTOPs a job and records its pids in this
+// ledger (`{ [rootPid]: [{ pid, started_at_ms }] }`, `{}` when nothing is
+// held) until it resumes them. a plain setTimeout keeps running across that
+// hold, so a command the paused browser could not answer times out for load
+// it never caused. a deadline only stops advancing while the pid it waits on
+// is held; a dead or unrelated process never extends it.
+const LEDGER_PATH = path.join(
+  process.env.TM_HOME || path.join(os.homedir(), '.team-machine'),
+  'governor-pauses.json',
+)
+const TICK_MS = 500
+
+interface Timer {
+  hostPid: number
+  remaining: number
+  accountedAt: number
+  fire: () => void
+}
+
+const timers = new Set<Timer>()
+let poll: ReturnType<typeof setInterval> | undefined
+
+function pausedPids(): number[] {
+  try {
+    const ledger: Record<string, { pid: number }[]> = JSON.parse(
+      readFileSync(LEDGER_PATH, 'utf8'),
+    )
+    return Object.values(ledger).flatMap((procs) => procs.map((proc) => proc.pid))
+  } catch {
+    return []
+  }
+}
+
+// the pids in `paused` that are `rootPid` or descend from it, by ps ancestry.
+function heldRoots(paused: number[], roots: Set<number>): Set<number> {
+  const parents = new Map<number, number>()
+  for (const line of execFileSync('ps', ['-A', '-o', 'pid=,ppid='], {
+    encoding: 'utf8',
+  }).split('\n')) {
+    const [pid, ppid] = line.trim().split(/\s+/).map(Number)
+    if (pid && ppid !== undefined) parents.set(pid, ppid)
+  }
+  const held = new Set<number>()
+  for (const start of paused) {
+    for (let pid: number | undefined = start, hops = 0; pid && hops < 64; hops++) {
+      if (roots.has(pid)) {
+        held.add(pid)
+        break
+      }
+      pid = parents.get(pid)
+    }
+  }
+  return held
+}
+
+function tick() {
+  const now = Date.now()
+  const paused = pausedPids()
+  const held = paused.length
+    ? heldRoots(paused, new Set([...timers].map((timer) => timer.hostPid)))
+    : new Set<number>()
+  for (const timer of [...timers]) {
+    // each timer accounts only since its own creation or last accounting
+    if (!held.has(timer.hostPid)) timer.remaining -= now - timer.accountedAt
+    timer.accountedAt = now
+    if (timer.remaining <= 0) {
+      timers.delete(timer)
+      timer.fire()
+    }
+  }
+  if (timers.size === 0 && poll) {
+    clearInterval(poll)
+    poll = undefined
+  }
+}
+
+// like setTimeout, but the budget does not advance while the governor holds
+// `hostPid` (the browser host the command waits on) or a descendant paused.
+// one shared poll serves every timer. returns the clear function.
+export function setPauseAwareTimeout(
+  fn: () => void,
+  budgetMs: number,
+  hostPid: number | undefined,
+): () => void {
+  if (hostPid === undefined) {
+    const timer = setTimeout(fn, budgetMs)
+    return () => clearTimeout(timer)
+  }
+  const timer: Timer = { hostPid, remaining: budgetMs, accountedAt: Date.now(), fire: fn }
+  timers.add(timer)
+  if (!poll) {
+    poll = setInterval(tick, TICK_MS)
+  }
+  return () => {
+    timers.delete(timer)
+  }
+}

package/cli/remote-simulators.ts

@@ -0,0 +1,112 @@
+import {
+  cloudBoxConnectUrl,
+  deleteCloudBox,
+  resolveCloudBoxReference,
+} from 'peach-cloud-box/client'
+import { isRecord } from '../src/is-record'
+import { deleteRemoteSim, listRemoteSims } from './cloud-client'
+import type {
+  AccountRemoteSimulator,
+  HostedRemoteSimulator,
+  RemoteSimulatorAccount,
+} from './remoteSimulatorContract'
+
+// the account's meter is the existing index of hosted simulators. shell-only
+// boxes have no simulator session and do not belong in this list.
+async function listHostedSimulators(
+  account: RemoteSimulatorAccount,
+): Promise<HostedRemoteSimulator[]> {
+  const query = new URLSearchParams({ kind: 'sim', status: 'running' })
+  if (account.accountId) query.set('accountId', account.accountId)
+  const response = await fetch(
+    `${account.apiOrigin.replace(/\/+$/, '')}/api/v1/rnx/sessions?${query}`,
+    {
+      headers: { authorization: account.authorization },
+      signal: AbortSignal.timeout(30_000),
+    },
+  )
+  if (!response.ok) {
+    throw new Error(`hosted simulator list ${response.status}: ${await response.text()}`)
+  }
+  const parsed: unknown = await response.json()
+  if (!isRecord(parsed) || !Array.isArray(parsed.sessions)) {
+    throw new Error('hosted simulator list returned invalid JSON')
+  }
+  const sims: HostedRemoteSimulator[] = []
+  for (const session of parsed.sessions) {
+    if (!isRecord(session))
+      throw new Error('hosted simulator list returned an invalid session')
+    if (
+      session.kind !== 'sim' ||
+      session.size !== 'micro' ||
+      session.status !== 'running'
+    )
+      continue
+    if (
+      typeof session.boxId !== 'string' ||
+      !session.boxId ||
+      (session.name !== null && typeof session.name !== 'string') ||
+      (session.device !== null && typeof session.device !== 'string') ||
+      typeof session.startedAt !== 'number' ||
+      !Number.isFinite(session.startedAt) ||
+      typeof session.meteredMs !== 'number' ||
+      !Number.isFinite(session.meteredMs)
+    ) {
+      throw new Error('hosted simulator list returned an invalid simulator')
+    }
+    sims.push({
+      service: 'box',
+      simId: session.boxId,
+      name: session.name,
+      status: 'running',
+      device: session.device,
+      startedAt: session.startedAt,
+      meteredMs: session.meteredMs,
+    })
+  }
+  return sims
+}
+
+export async function listAccountRemoteSimulators(
+  account: RemoteSimulatorAccount,
+): Promise<AccountRemoteSimulator[]> {
+  const [hosted, nano] = await Promise.all([
+    listHostedSimulators(account),
+    listRemoteSims({
+      authorization: account.authorization,
+      accountId: account.accountId,
+    }),
+  ])
+  return [
+    ...hosted,
+    ...nano.map((sim): AccountRemoteSimulator => ({ ...sim, service: 'sim' })),
+  ]
+}
+
+export async function stopAccountRemoteSimulator(
+  account: RemoteSimulatorAccount,
+  simId: string,
+): Promise<{ simId: string } | null> {
+  const hosted = await listHostedSimulators(account)
+  const sim = hosted.find((candidate) => candidate.simId === simId)
+  if (!sim)
+    return deleteRemoteSim({
+      authorization: account.authorization,
+      accountId: account.accountId,
+      simId,
+    })
+
+  // resolve through the account service before addressing a host. another
+  // account's id must never turn into a provider request with this key.
+  const reference = await resolveCloudBoxReference({
+    apiOrigin: account.apiOrigin,
+    apiKey: account.authorization.replace(/^Bearer /, ''),
+    accountId: account.accountId,
+    boxId: sim.simId,
+  })
+  await deleteCloudBox({
+    connectUrl: cloudBoxConnectUrl(reference.endpoint, reference.boxId),
+    accessToken: account.authorization.replace(/^Bearer /, ''),
+  })
+  return { simId: sim.simId }
+}

package/cli/remoteSimulatorContract.ts

@@ -0,0 +1,21 @@
+import type { RnxCloudSimView } from '../src/cloud-contract'
+
+export interface HostedRemoteSimulator {
+  service: 'box'
+  simId: string
+  name: string | null
+  status: 'running'
+  device: string | null
+  startedAt: number
+  meteredMs: number
+}
+
+export type AccountRemoteSimulator =
+  | (RnxCloudSimView & { service: 'sim' })
+  | HostedRemoteSimulator
+
+export interface RemoteSimulatorAccount {
+  apiOrigin: string
+  authorization: string
+  accountId: string | null
+}