peachsim 0.1.527

package/cli/commands/inspect/count.ts

@@ -0,0 +1,17 @@
+// `rnx get count` — total SootSimNode count in the live tree.
+
+import { inspectNodeCount } from './core'
+import { printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runCountSubcommand(
+  bridge: WsBridge,
+  opts: { args: string[] } = { args: [] },
+): Promise<void> {
+  const result = await inspectNodeCount(bridge)
+  if (wantsJson(opts.args)) {
+    printJson(result)
+    return
+  }
+  console.log(`  nodes: ${result.nodes}`)
+}

package/cli/commands/inspect/describe.ts

@@ -0,0 +1,119 @@
+// `rnx describe` — format the pruned visible semantic tree.
+
+import { maybeHint } from '../../hints'
+import { inspectDescribe, type DescribeDumpOptions } from './core'
+import {
+  maybeWaitForStartedScreenTransitions,
+  printJson,
+  sleep,
+  wantsJson,
+} from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+export interface DescribeOptions {
+  bridge: WsBridge
+  args: string[]
+  positional: string[]
+}
+
+function flagValue(args: string[], name: string): string | null {
+  const i = args.indexOf(name)
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : null
+}
+
+export async function runDescribeSubcommand(opts: DescribeOptions): Promise<void> {
+  const { bridge, args, positional } = opts
+  const verbose = args.includes('--verbose') || args.includes('-v')
+  const jsonOut = wantsJson(args)
+  const verboseDescribeTransitions = verbose && !jsonOut
+  const watch = args.includes('--watch') || args.includes('-w')
+  const watchInterval = 1000
+  const compact = args.includes('--compact')
+  const hideXy = args.includes('--no-xy')
+  const testIdLike = flagValue(args, '--testid-like')
+  const onlyGlob = flagValue(args, '--only')
+  const subtreeRoot = flagValue(args, '--subtree')
+
+  // bare positional still works — routes to --only if it looks globby,
+  // otherwise preserves the old substring-match behavior as `filter`. guard
+  // against a flag-looking token leaking in as a filter: an unrecognized
+  // `--flag` that the arg parser didn't strip must never become a text filter
+  // (that's how `describe --compact` used to match nothing).
+  const positionalFilter =
+    positional[1] && !positional[1].startsWith('-') ? positional[1] : undefined
+  const bareIsGlob = positionalFilter ? /[*?]/.test(positionalFilter) : false
+  const filter = !bareIsGlob && !onlyGlob ? positionalFilter : undefined
+  const effectiveOnlyGlob = onlyGlob ?? (bareIsGlob ? positionalFilter : undefined)
+
+  const runOnce = async () => {
+    await maybeWaitForStartedScreenTransitions(bridge, {
+      verbose: verboseDescribeTransitions,
+    })
+    const dumpOpts: DescribeDumpOptions = {
+      describe: true,
+      verbose,
+      filter: filter || '',
+      testIdLike: testIdLike || undefined,
+      onlyGlob: effectiveOnlyGlob || undefined,
+      subtreeRoot: subtreeRoot || undefined,
+      compact,
+      hideXy,
+      // no terminal to fit, so nothing gets clipped on the way out
+      fullText: jsonOut,
+    }
+    const result = await inspectDescribe(bridge, dumpOpts)
+    const tree = result?.tree
+
+    if (jsonOut) {
+      printJson({ tree: tree ?? '' })
+      return
+    }
+
+    if (typeof tree === 'string' && tree.startsWith('__SUBTREE_NOT_FOUND__:')) {
+      const missing = tree.slice('__SUBTREE_NOT_FOUND__:'.length)
+      console.log(`  subtree root not found: ${missing}`)
+      maybeHint('subtree-root-not-found', missing)
+      return
+    }
+
+    if (!tree) {
+      const nodeCount = result?.nodeCount ?? 0
+      console.log('  no matching nodes found')
+      const anyFilterActive = filter || testIdLike || effectiveOnlyGlob || subtreeRoot
+      if (!anyFilterActive && nodeCount < 10) {
+        maybeHint('app-still-loading', nodeCount)
+      }
+      return
+    }
+
+    console.log(tree)
+
+    const anyFilterActive = filter || testIdLike || effectiveOnlyGlob || subtreeRoot
+    const searchFilterActive = filter || testIdLike || effectiveOnlyGlob
+    if (searchFilterActive && !watch) {
+      maybeHint('describe-filter-context')
+    }
+
+    // when no filter was active and the tree got long, nudge once per
+    // session toward the narrowing flags — this is exactly the case the
+    // user flagged where "which row is the swap sheet" got buried under
+    // 100+ lines of home content.
+    if (!anyFilterActive && !watch) {
+      const lineCount = tree.split('\n').length
+      if (lineCount >= 80) {
+        maybeHint('describe-use-filters')
+      }
+    }
+  }
+
+  if (watch) {
+    console.log('  watching... (Ctrl+C to stop)\n')
+    while (true) {
+      console.clear()
+      await runOnce()
+      await sleep(watchInterval)
+    }
+  } else {
+    await runOnce()
+  }
+}

package/cli/commands/inspect/env.ts

@@ -0,0 +1,25 @@
+// env vars that indicate the CLI is being driven by an agent/automation rather
+// than a human at a terminal. when any is present, auto-waits get a longer
+// budget and log more aggressively, because an agent can't see mid-animation
+// flicker the way a human can.
+const AGENT_ENV_VARS = [
+  'RNX_AGENT',
+  'TM_SESSION',
+  'CLAUDECODE',
+  'CLAUDE_CODE_ENTRYPOINT',
+  'CLAUDE_CODE_SESSION_ID',
+  'CODEX_THREAD_ID',
+  'CURSOR_TRACE_ID',
+  'AIDER_MODEL',
+]
+
+export function isAgentEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  if (env.RNX_AGENT === '0') return false
+  for (const name of AGENT_ENV_VARS) {
+    const v = env[name]
+    if (v && v.trim() && v !== '0') return true
+  }
+  return false
+}

package/cli/commands/inspect/find.ts

@@ -0,0 +1,169 @@
+import { maybeHint } from '../../hints'
+import { rnxExit } from '../../run-rnx'
+import { inspectFind, inspectNodeCount, rankInteractive, tapCommandForNode } from './core'
+import { printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+// unified finder: one verb for text/testid/role/type/pressable/visible.
+// --testid (not --id) keeps element lookup distinct from target selection.
+// mode resolution + the evaluated JS live in inspect/core.ts (shared with the
+// agent); this handler only parses flags and formats the result for the CLI.
+export async function runFindSubcommand(opts: {
+  bridge: WsBridge
+  args: string[]
+  effectiveArgs: string[]
+  positional: string[]
+  inspectUsage: (name: string, tail: string) => string
+}): Promise<void> {
+  const { bridge, args, effectiveArgs, positional, inspectUsage } = opts
+
+  const findFlag = (name: string): string | null => {
+    const i = effectiveArgs.indexOf(name)
+    return i >= 0 && i + 1 < effectiveArgs.length ? effectiveArgs[i + 1] : null
+  }
+  const hasFlag = (name: string): boolean => effectiveArgs.includes(name)
+
+  const testId = findFlag('--testid') || findFlag('--test-id')
+  const role = findFlag('--role')
+  const typeFlag = findFlag('--type')
+  const textFlag = findFlag('--text')
+  const pressable = hasFlag('--pressable')
+  const visible = hasFlag('--visible')
+  // ranked-tappable list — same data source as --pressable, but the
+  // output prioritises high-signal targets the agent likely wants to
+  // tap next (visible, has text or testID, has accessibilityLabel),
+  // and emits a copy-paste `rnx do` command per row so the agent
+  // doesn't have to re-form a tap from raw fields.
+  const interactive = hasFlag('--interactive-targets') || hasFlag('--actions')
+  const bareText =
+    !testId && !role && !typeFlag && !textFlag && !pressable && !visible && !interactive
+      ? positional[1]
+      : null
+  const textQuery = textFlag ?? bareText
+
+  const found = await inspectFind(bridge, {
+    testId,
+    role,
+    type: typeFlag,
+    text: textQuery,
+    pressable,
+    visible,
+    interactive,
+  })
+  if (!found) {
+    console.error(
+      inspectUsage(
+        'find',
+        '<text> | --text <t> | --testid <id> | --role <r> | --type <t> | --pressable | --visible | --interactive-targets',
+      ),
+    )
+    rnxExit(1)
+  }
+  const { mode, result } = found
+  const jsonOut = wantsJson(args)
+  // --verbose / --dump: emit full node JSON per result instead of just the
+  // one-line summary. the default summary is compact for scannability; when
+  // you already know the match and need to copy testID / layout / a11y
+  // props, --verbose saves the round-trip through `get node <id>`.
+  const verbose = args.includes('--verbose') || args.includes('--dump')
+
+  if (jsonOut) {
+    if (mode === 'interactive-targets' && Array.isArray(result)) {
+      // include the `tap` command per row when emitting JSON for agents
+      // — the human renderer does the same. tooling that drives rnx
+      // can pick the highest-scored entry and execute its `tap` field.
+      printJson(rankInteractive(result).map((n) => ({ ...n, tap: tapCommandForNode(n) })))
+    } else {
+      printJson(result ?? null)
+    }
+  } else if (Array.isArray(result)) {
+    if (result.length === 0) {
+      console.log(`  no ${mode} nodes found`)
+      const { nodes: nodeCount } = await inspectNodeCount(bridge)
+      if (nodeCount < 10) {
+        maybeHint('app-still-loading', nodeCount)
+      }
+    } else if (mode === 'interactive-targets') {
+      const ranked = rankInteractive(result)
+      console.log(
+        `  found ${ranked.length} interactive target${ranked.length === 1 ? '' : 's'} (sorted by score):`,
+      )
+      for (const n of ranked.slice(0, 20)) {
+        const loc = n.absolutePosition
+          ? `@(${Math.round(n.absolutePosition.x)},${Math.round(n.absolutePosition.y)})`
+          : ''
+        const size = n.layout
+          ? `${Math.round(n.layout.width)}x${Math.round(n.layout.height)}`
+          : '?x?'
+        const text = n.text ? ` "${n.text.slice(0, 30)}"` : ''
+        const tid = n.testID ? ` #${n.testID}` : ''
+        const label = n.accessibilityLabel
+          ? ` ⓘ"${String(n.accessibilityLabel).slice(0, 24)}"`
+          : ''
+        const roleName = n.accessibilityRole ? `[${n.accessibilityRole}]` : n.type
+        const tapCmd = tapCommandForNode(n)
+        console.log(`    ${roleName}${text}${label}${tid} ${size} ${loc}`)
+        console.log(`      → ${tapCmd}`)
+        if (verbose) console.log(indent(JSON.stringify(n, null, 2), '      '))
+      }
+      if (ranked.length > 20) console.log(`    ... and ${ranked.length - 20} more`)
+    } else {
+      console.log(
+        `  found ${result.length} node${result.length === 1 ? '' : 's'} (${mode}):`,
+      )
+      for (const n of result.slice(0, 20)) {
+        const loc = n.absolutePosition
+          ? `@(${Math.round(n.absolutePosition.x)},${Math.round(n.absolutePosition.y)})`
+          : ''
+        const size = n.layout
+          ? `${Math.round(n.layout.width)}x${Math.round(n.layout.height)}`
+          : '?x?'
+        const text = n.text ? ` "${n.text.slice(0, 30)}"` : ''
+        const tid = n.testID ? ` #${n.testID}` : ''
+        const tap = n.pressable ? ' (tap)' : ''
+        const roleName = n.accessibilityRole ? `[${n.accessibilityRole}]` : n.type
+        console.log(`    ${roleName}${text}${tid} ${size} ${loc}${tap}`)
+        if (verbose) console.log(indent(JSON.stringify(n, null, 2), '      '))
+      }
+      if (result.length > 20) console.log(`    ... and ${result.length - 20} more`)
+    }
+  } else if (result == null) {
+    const query = textQuery || testId || role || typeFlag || ''
+    console.log(`  not found: ${query || mode}`)
+    if (testId) {
+      maybeHint('wait-selector-for-missing-testid', testId)
+    }
+  } else {
+    interface InspectNode {
+      type?: string
+      absolutePosition?: { x: number; y: number }
+      layout?: { width: number; height: number }
+      text?: string
+      testID?: string
+      pressable?: boolean
+      accessibilityRole?: string
+    }
+    const n = result as InspectNode
+    if (n.type && n.absolutePosition) {
+      const loc = `@(${Math.round(n.absolutePosition.x)},${Math.round(n.absolutePosition.y)})`
+      const size = n.layout
+        ? `${Math.round(n.layout.width)}x${Math.round(n.layout.height)}`
+        : '?x?'
+      const text = n.text ? ` "${n.text.slice(0, 40)}"` : ''
+      const tid = n.testID ? ` #${n.testID}` : ''
+      const tap = n.pressable ? ' (tap)' : ''
+      const roleName = n.accessibilityRole ? `[${n.accessibilityRole}]` : n.type
+      console.log(`  ${roleName}${text}${tid} ${size} ${loc}${tap}`)
+      if (verbose) console.log(indent(JSON.stringify(n, null, 2), '    '))
+    } else {
+      console.log(JSON.stringify(result, null, 2))
+    }
+  }
+}
+
+function indent(text: string, prefix: string): string {
+  return text
+    .split('\n')
+    .map((line) => prefix + line)
+    .join('\n')
+}

package/cli/commands/inspect/get-layout.ts

@@ -0,0 +1,53 @@
+// `rnx get-layout` — bounding boxes for visible meaningful elements on the
+// current screen. focused on the layout numbers a designer checks: on-screen
+// box (x/y/w/h). pass --styling for computed borderRadius, per-side padding,
+// fontSize, visual style fields, and native rendered text contrast. pass
+// --filter <text> to narrow to the elements whose text/testID/role/selector
+// match — fewer rows, full detail on each, which is how you read one area's
+// styling without the whole screen.
+//
+// the extraction + formatting live in the shared `./core` kernel
+// (inspectGetLayout / formatLayoutElements) so this CLI command and the agent's
+// app_get_layout tool produce identical output. the CLI-side job is just:
+// optional preflight for in-flight screen transitions, call the kernel, print.
+
+import { formatLayoutElements, inspectGetLayout } from './core'
+import { maybeWaitForStartedScreenTransitions, printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runGetLayoutSubcommand(opts: {
+  bridge: WsBridge
+  args: string[]
+}): Promise<void> {
+  const { bridge, args } = opts
+  const jsonOut = wantsJson(args)
+  await maybeWaitForStartedScreenTransitions(bridge, { verbose: !jsonOut })
+  const styling = args.includes('--styling')
+  const filterIndex = args.indexOf('--filter')
+  const filter = filterIndex >= 0 ? args[filterIndex + 1] : undefined
+  const elements = await inspectGetLayout(bridge, { styling, filter }).catch(
+    (error: unknown) => {
+      if (
+        styling &&
+        error instanceof Error &&
+        (error.message === 'unsupported RNX Cloud command type: evaluate' ||
+          error.message.includes('requires the debug scope'))
+      ) {
+        throw new Error(
+          'get layout --styling is unavailable on a remote simulator; rerun without --styling or use a local sim',
+        )
+      }
+      throw error
+    },
+  )
+  if (jsonOut) {
+    printJson({ count: elements.length, elements })
+    return
+  }
+  console.log(
+    `  layout (${elements.length} element${elements.length === 1 ? '' : 's'}):\n`,
+  )
+  // styling fields (including native rendered text contrast) are opt-in via
+  // --styling so the default inspect output stays scannable.
+  console.log(formatLayoutElements(elements, { styling }))
+}

package/cli/commands/inspect/keyboard.ts

@@ -0,0 +1,54 @@
+// `rnx get keyboard` — prints the current iOS keyboard's full state.
+//
+// shows visibility, keyboardType, returnKeyType, autoCapitalize policy,
+// active QWERTY sub-mode, shift + capsLock, and the mounted accessory bar
+// id (if any). reads from `__sootsimKeyboard.getLayout()`, which is
+// populated by shell-worker `keyboard.layout` broadcasts.
+
+import { rnxExit } from '../../run-rnx'
+import { inspectKeyboard } from './core'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runKeyboardSubcommand(
+  bridge: WsBridge,
+  opts: { json?: boolean } = {},
+): Promise<void> {
+  const result = await inspectKeyboard(bridge)
+
+  if ('error' in result) {
+    console.error(result.error)
+    rnxExit(1)
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+
+  const { visible, spec, mode, shifted, capsLock, accessoryBarId } = result
+  const lines: string[] = []
+  lines.push(`keyboard: ${visible ? 'visible' : 'hidden'}`)
+  if (spec) {
+    lines.push(`  type:          ${spec.keyboardType}`)
+    lines.push(`  returnKey:     ${spec.returnKeyType}`)
+    lines.push(`  autoCap:       ${spec.autoCapitalize}`)
+    lines.push(`  autoCorrect:   ${spec.autoCorrect ? 'on' : 'off'}`)
+    lines.push(`  spellCheck:    ${spec.spellCheck ? 'on' : 'off'}`)
+    lines.push(`  appearance:    ${spec.keyboardAppearance}`)
+    if (spec.secureTextEntry) lines.push(`  secureTextEntry: true`)
+    if (spec.enablesReturnKeyAutomatically) {
+      lines.push(
+        `  return:        ${spec.currentTextIsEmpty ? 'disabled (empty)' : 'enabled'}`,
+      )
+    }
+  } else {
+    lines.push(`  spec:          <none> (shown via dev-tools with no TextInput)`)
+  }
+  lines.push(
+    `  mode:          ${mode}${shifted ? ' (shifted)' : ''}${capsLock ? ' (caps)' : ''}`,
+  )
+  if (accessoryBarId) {
+    lines.push(`  accessoryBar:  ${accessoryBarId}`)
+  }
+  console.log(lines.join('\n'))
+}

package/cli/commands/inspect/list.ts

@@ -0,0 +1,175 @@
+// `rnx list` — connected sims, with the active one marked.
+
+import { resolveDevCheckoutRuntimeRoot } from '../../../src/runtime-assets'
+import { type BridgeSimInfo, formatLockOwner, type WsBridge } from '../../ws-bridge'
+import { printJson, wantsJson } from './shared'
+
+export async function runListSubcommand(opts: {
+  bridge: WsBridge
+  simId: string | undefined
+  args: string[]
+}): Promise<void> {
+  const sims = await opts.bridge.listSims()
+
+  // filter sims:
+  //   --all                       show every sim including empty shells (default
+  //                               hides sims that have no bundle URL — they're
+  //                               usually idle host shells that overflow the
+  //                               list when several demos are open at once)
+  //   --bundle <substring>        only sims whose loaded url contains the substring
+  //   --app-port <port>           shorthand for `--bundle :<port>/`. NOT `--port`
+  //                               which is taken by the global bridge-port flag
+  //                               (see ws-bridge.ts parseBridgeCliArgs) — using
+  //                               --port here used to silently set the bridge
+  //                               port too, sending the WS connect to the wrong
+  //                               place and failing with "daemon is not running"
+  //   --primary                   only the primary sim
+  const showAll = opts.args.includes('--all')
+  const bundleArg = opts.args.find((_, i) => opts.args[i - 1] === '--bundle')
+  const portArg = opts.args.find((_, i) => opts.args[i - 1] === '--app-port')
+  const primaryOnly = opts.args.includes('--primary')
+  const filtered = sims.filter((sim) => {
+    if (primaryOnly && !sim.isPrimary) return false
+    if (bundleArg && !(sim.url ?? '').includes(bundleArg)) return false
+    // a sim url looks like `http://localhost:5173/rn/8085?bundle=...` where
+    // `8085` is the metro/vite port the app is loaded from. the bundle url
+    // inside the `?bundle=` param is itself percent-encoded (`:8085/` ->
+    // `%3A8085%2F`), so the previous literal `:${port}/` substring check
+    // never matched. match the canonical `/rn/<port>` path segment instead.
+    if (portArg && !(sim.url ?? '').includes(`/rn/${portArg}`)) return false
+    if (!showAll && !bundleArg && !portArg && !primaryOnly) {
+      // hide host shells (no bundle loaded — only origin) unless they're
+      // the currently-selected sim
+      const hasBundle =
+        sim.url && (sim.url.includes('bundle=') || sim.url.includes('/index.bundle'))
+      if (!hasBundle && sim.id !== opts.simId) return false
+    }
+    return true
+  })
+
+  if (wantsJson(opts.args)) {
+    printJson(filtered.map((b) => ({ ...b, active: b.id === opts.simId })))
+    return
+  }
+  printConnectedSims(filtered, opts.simId)
+  if (filtered.length < sims.length && !wantsJson(opts.args)) {
+    console.log(`  (${sims.length - filtered.length} more hidden — pass --all to show)`)
+  }
+}
+
+// returns a short, human-friendly description of what a sim is showing —
+// e.g. "bundle host/...path", "connect :8081", "demo bluesky". returns null
+// when there's no useful summary beyond the raw URL itself, so the caller
+// can skip the redundant `loaded:` line in that case.
+function summarizeSimUrl(url: string | undefined): string | null {
+  if (!url) return null
+  try {
+    const parsed = new URL(url)
+    if (parsed.searchParams.has('bundle')) {
+      const bundleUrl = parsed.searchParams.get('bundle') || ''
+      try {
+        const bundle = new URL(bundleUrl)
+        const shortPath =
+          bundle.pathname.length > 36
+            ? `...${bundle.pathname.slice(-36)}`
+            : bundle.pathname
+        return `bundle ${bundle.host}${shortPath}`
+      } catch {
+        return 'bundle'
+      }
+    }
+    if (parsed.searchParams.has('port')) {
+      return `connect :${parsed.searchParams.get('port') || ''}`
+    }
+    if (parsed.searchParams.has('open')) {
+      return `connect ${parsed.searchParams.get('open') || ''}`
+    }
+    if (parsed.searchParams.has('demo')) {
+      return `demo ${parsed.searchParams.get('demo') || 'default'}`
+    }
+    if (
+      parsed.pathname.includes('/sootsim/index.html') ||
+      parsed.pathname === '/sootsim/' ||
+      parsed.pathname === '/sootsim'
+    ) {
+      return 'embedded rnx'
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+function printConnectedSims(sims: BridgeSimInfo[], selectedId?: string) {
+  if (sims.length === 0) {
+    console.log('  no sims connected')
+    return
+  }
+  console.log(`  connected sims (${sims.length}):\n`)
+  for (const sim of sims) {
+    const lockTag =
+      sim.lockedBy && sim.lockExpiresAt
+        ? `locked by ${formatLockOwner(sim.lockedBy)} (${Math.max(0, Math.round((sim.lockExpiresAt - Date.now()) / 1000))}s)`
+        : ''
+    const tags = [
+      sim.isPrimary ? 'primary' : '',
+      sim.id === selectedId ? 'selected' : '',
+      sim.readyState,
+      sim.userVisible === false ? 'hidden' : sim.userVisible === true ? 'visible' : '',
+      sim.attachedCliCount && sim.attachedCliCount > 0 ? 'in use' : '',
+      sim.userFocused ? 'focused' : '',
+      lockTag,
+    ].filter(Boolean)
+    console.log(`  ${sim.id}${tags.length ? ` [${tags.join(', ')}]` : ''}`)
+    const loaded = summarizeSimUrl(sim.url)
+    if (loaded) {
+      console.log(`    loaded: ${loaded}`)
+    } else if (sim.url) {
+      // no friendly summary — show the raw url so the caller can still copy it.
+      // truncate aggressively so a 400-char metro url doesn't dominate the list.
+      const shown = sim.url.length > 96 ? `${sim.url.slice(0, 93)}…` : sim.url
+      console.log(`    url: ${shown}`)
+    } else if (sim.origin) {
+      console.log(`    origin: ${sim.origin}`)
+    }
+    const engine = describeEngineSource(sim)
+    if (engine) console.log(`    engine: ${engine}`)
+    if (sim.title) console.log(`    title: ${sim.title}`)
+    if (sim.visibilityState && sim.visibilityState !== 'visible') {
+      console.log(`    visibility: ${sim.visibilityState}`)
+    }
+    console.log(`    connected: ${formatRelativeAge(Date.now() - sim.connectedAt)}`)
+    if (sim.lastActiveAt && sim.lastActiveAt > 0) {
+      console.log(`    last active: ${formatRelativeAge(Date.now() - sim.lastActiveAt)}`)
+    }
+  }
+}
+
+// classify which engine a sim is running so dev-vs-published is never ambiguous
+// to agents or humans reading `rnx list`. dev shell serves local source on
+// :5173; the Contrast app embeds rnx on :3000; the bridge/daemon and the
+// /__soot plugin serve the active runtime dir — which, inside a dev checkout, is
+// the fresh dev-stack build (resolveDevCheckoutRuntimeRoot mode boundary), not a
+// published runtime. keep this label honest so it never says "published" while
+// actually serving local build output.
+function describeEngineSource(sim: { url?: string; origin?: string }): string | null {
+  const ref = sim.url || sim.origin || ''
+  if (!ref) return null
+  try {
+    const port = new URL(ref).port
+    if (port === '5173') return 'dev — local source (:5173)'
+    if (port === '3000') return 'Contrast app embedded (:3000)'
+    if (resolveDevCheckoutRuntimeRoot()) return `dev — local build (:${port || '?'})`
+    return `runtime — published engine (:${port || '?'})`
+  } catch {
+    return null
+  }
+}
+
+function formatRelativeAge(ms: number): string {
+  const sec = Math.max(0, Math.round(ms / 1000))
+  if (sec < 60) return `${sec}s ago`
+  if (sec < 3600) return `${Math.round(sec / 60)}m ago`
+  if (sec < 86400) return `${Math.round(sec / 3600)}h ago`
+  return `${Math.round(sec / 86400)}d ago`
+}