peachsim 0.1.577 → 0.1.579

package/cli/commands/control.ts

@@ -2,9 +2,11 @@ import { spawn, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { encodeAppCatalogWire } from 'peach-engine/engine/app-catalog-wire'
 import {
   devices,
   listSelectableDeviceModels,
+  resolveDeviceFitBox,
   type DeviceModel,
 } from 'peach-engine/settings'
 import { WebSocket } from 'ws'
@@ -41,6 +43,8 @@ import {
   runtimeVersionHostname,
 } from '../../src/runtime-assets'
 import { rnxRuntime } from '../../src/runtime-delivery'
+import { sleep } from '../../src/sleep'
+import { discoverAppCatalog } from '../app-catalog'
 import { loadRNXAppConfig } from '../app-config'
 import {
   type DiscoveredAppFontSpec,
@@ -108,10 +112,6 @@ const SHELL_APPS: Record<string, string> = {
   camera: '/app/camera',
 }
 
-function sleep(ms: number) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
 function parsePositiveIntegerEnv(name: string): number | null {
   const value = process.env[name]?.trim()
   if (!value) return null
@@ -176,14 +176,19 @@ export async function ensureBridgeForOpen(
   const lock = readDaemonLockfile()
   assertExplicitBridgeLock(preferredPort, explicitPort, lock)
   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.
   if (
     (explicitPort || preferredWorld !== null) &&
-    (await canConnectToBridge(preferredPort, 250))
+    (await canConnectToBridge(preferredPort, 2_000))
   ) {
     return preferredPort
   }
   if (explicitPort && preferredWorld !== null) {
-    throw new Error(`peach open: requested bridge port ${preferredPort} is not reachable.`)
+    throw new Error(
+      `peach open: requested bridge port ${preferredPort} is not reachable.`,
+    )
   }
   if (
     !explicitPort &&
@@ -210,7 +215,21 @@ export async function ensureBridgeForOpen(
   const deadline = Date.now() + OPEN_BRIDGE_SPAWN_TIMEOUT_MS
   while (Date.now() < deadline) {
     const nextLock = readDaemonLockfile()
-    assertExplicitBridgeLock(preferredPort, explicitPort, nextLock)
+    if (
+      explicitPort &&
+      nextLock &&
+      isDaemonLockfileFresh(nextLock) &&
+      nextLock.bridgePort !== preferredPort
+    ) {
+      // serve fell back because something already holds the pinned port. the
+      // bridge it started is one nobody asked for: stop it, and use the pinned
+      // port if what holds it is a bridge that answers given longer.
+      child.kill()
+      if (await canConnectToBridge(preferredPort, 5_000)) return preferredPort
+      throw new Error(
+        `peach open: requested bridge port ${preferredPort} is held by a process that does not answer as a peach bridge.`,
+      )
+    }
     const selectedPort = explicitPort ? preferredPort : nextLock?.bridgePort
     if (
       nextLock &&
@@ -261,6 +280,9 @@ function assertExplicitBridgeLock(
 }
 
 async function ensureRuntimeForOpen() {
+  // a dev checkout serves its own build; staging a published runtime into an
+  // isolated home would make the daemon serve that instead.
+  if (resolveDevCheckoutRuntimeRoot()) return
   const active = readActiveRuntime()
   if (active && fs.existsSync(runtimeDir(active))) return
   console.error('  installing peach engine runtime...')
@@ -351,7 +373,7 @@ function buildShellPathOpenUrl(target: string, baseUrl: string): string {
   return url.toString()
 }
 
-// peach share/preview/build links (e.g. https://rnxsim.com/preview/<id>,
+// peach share/preview/build links (e.g. https://peachsim.com/preview/<id>,
 // https://contrast.dev/build/<owner>/<repo>/<branch>) are full player pages
 // served by the Contrast app — NOT Metro bundles and NOT driveable shell sims.
 // passing one to `peach open` used to fall through to the bundle resolver,
@@ -374,12 +396,6 @@ function looksLikeSootSimShareUrl(target: string): boolean {
   }
 }
 
-export async function resolveBundleTarget(target: string): Promise<string> {
-  const normalized = normalizeKnownTarget(target)
-  const resolved = await resolveConnectionInputForCli(normalized)
-  return resolved.bundleUrl
-}
-
 function localBasePort(target: string): number | null {
   try {
     const url = new URL(target.startsWith('http') ? target : `http://${target}`)
@@ -749,6 +765,23 @@ async function stampAppSplash(
   }
 }
 
+// stamp the engine page url with `?appCatalog=` so an app's asset-catalog
+// colors and its declared accent reach the tenant, which applies them to the
+// bundle this url opens. the catalog lives in the native binary, never in
+// the js bundle, so only the app's ios project on disk has it.
+function stampAppCatalog(urlStr: string, project?: ResolvedAppProject | null): string {
+  try {
+    const url = new URL(urlStr)
+    if (!url.searchParams.get('bundle') || !project) return urlStr
+    const catalog = discoverAppCatalog(project.appDir)
+    if (!catalog) return urlStr
+    url.searchParams.set('appCatalog', encodeAppCatalogWire(catalog))
+    return url.toString()
+  } catch {
+    return urlStr
+  }
+}
+
 async function splashImageReachable(imageUrl: string): Promise<boolean> {
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), 1500)
@@ -775,6 +808,17 @@ export interface BuildShellUrlOptions {
   // uses the same param. without this, every driver-opened sim silently ran
   // whatever profile the shell last persisted.
   device?: string
+  // fold posture (open|closed) stamped onto the engine URL as ?posture= next
+  // to ?device=. the shell reads it at boot (readUrlSettingOverrides) and
+  // keeps it in the URL on every pose change, so it round-trips the way
+  // device and orientation do. without this a manual ?posture= appended
+  // after the app path lands inside the bundle param and never reaches the
+  // shell. non-foldable devices resolve it to closed at boot.
+  posture?: string
+  // portrayed os version (major.minor) stamped as ?osVersion=, which the
+  // shell pins at boot over the device profile's own version. an oracle on a
+  // newer os than the profile compares only when the sim runs that os era.
+  osVersion?: string
   resolvedBundle?: ResolvedDevBundle
   project?: ResolvedAppProject | null
   // deterministic-capture mode, stamped onto the engine URL as ?proof=1. the
@@ -810,10 +854,15 @@ export async function buildShellUrl(
   // fallback typeface, which then reads as a conformance diff.
   const project =
     opts.project ?? (await resolveAppProjectForBundleUrl(bundleUrlOf(resolved)))
-  const stamped = await stampAppSplash(await stampAppFonts(resolved, project), project)
-  if (!opts.device && !opts.proof) return stamped
+  const stamped = stampAppCatalog(
+    await stampAppSplash(await stampAppFonts(resolved, project), project),
+    project,
+  )
+  if (!opts.device && !opts.proof && !opts.posture && !opts.osVersion) return stamped
   const url = new URL(stamped)
   if (opts.device) url.searchParams.set('device', opts.device)
+  if (opts.posture) url.searchParams.set('posture', opts.posture)
+  if (opts.osVersion) url.searchParams.set('osVersion', opts.osVersion)
   if (opts.proof) url.searchParams.set('proof', '1')
   return url.toString()
 }
@@ -837,9 +886,11 @@ function deriveCurrentSimBaseUrl(
     // and `stampAppFonts` doesn't get the chance to re-derive against the
     // current bundle. drop it so the rebuild starts clean.
     url.searchParams.delete('appFonts')
-    // appSplash is target-specific in the same way — drop it so the configured
-    // splash re-derives against the current bundle.
+    // appSplash and appCatalog are target-specific in the same way: drop them
+    // so the configured splash and catalog re-derive against the current
+    // bundle.
     url.searchParams.delete('appSplash')
+    url.searchParams.delete('appCatalog')
     return url.toString()
   } catch {
     return fallback
@@ -1182,6 +1233,12 @@ export function printOpenedSim(
   console.log(JSON.stringify({ simId: sim.id, url: printableSimUrl }, null, 2))
 }
 
+function printAgentListenHint(quiet: boolean): void {
+  if (!quiet) {
+    console.log('  inspect messages: run `peach agent listen` when you finish your turn')
+  }
+}
+
 // after a successful open, agents almost always want to know what's on the
 // screen. running describe inline saves a separate roundtrip. tightly
 // bounded — a cold guest bundle takes 5-15s to fully route, so we don't
@@ -1343,6 +1400,8 @@ export async function runOpenCommand(
       '--profile',
       '--cdp-port',
       '--device',
+      '--posture',
+      '--os-version',
       '--viewport',
     ],
   })
@@ -1475,7 +1534,9 @@ export async function runOpenCommand(
   // native desktop surface. neither path opens the user's browser profile.
   const requestedDriverId = args.find((_, i) => args[i - 1] === '--driver') || ''
   if (requestedDriverId && !isDriverId(requestedDriverId)) {
-    console.error(`  unknown driver "${requestedDriverId}" — run \`peach list --drivers\``)
+    console.error(
+      `  unknown driver "${requestedDriverId}" — run \`peach list --drivers\``,
+    )
     rnxExit(1)
   }
   const driverId: DriverId = isDriverId(requestedDriverId)
@@ -1518,7 +1579,38 @@ export async function runOpenCommand(
     console.error(`  known devices: ${listSelectableDeviceModels().join(', ')}`)
     rnxExit(1)
   }
-  const deviceSpec = deviceArg ? devices[deviceArg as DeviceModel] : undefined
+
+  // --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
+  // being swallowed into the bundle param. only foldable devices (iphone-duo)
+  // have a second posture; anything else resolves to closed at boot.
+  const postureArg = args.find((_, i) => args[i - 1] === '--posture')
+  if (postureArg && postureArg !== 'open' && postureArg !== 'closed') {
+    console.error(`  peach open: --posture must be open or closed, got "${postureArg}"`)
+    rnxExit(1)
+  }
+  // the window fits the box the browser stage fits the device into, which for
+  // a foldable spans every posture and orientation, so the device draws at its
+  // natural size in the pose it opens in instead of shrinking into a window
+  // sized for one pose.
+  const deviceFitBox = deviceArg
+    ? resolveDeviceFitBox(
+        deviceArg as DeviceModel,
+        false,
+        undefined,
+        postureArg === 'open' ? 'open' : 'closed',
+        true,
+      )
+    : undefined
+
+  // --os-version <major.minor> pins the portrayed os over the profile's.
+  const osVersionArg = args.find((_, i) => args[i - 1] === '--os-version')
+  if (osVersionArg && !/^\d+\.\d+$/.test(osVersionArg)) {
+    console.error(
+      `  peach open: --os-version must be <major>.<minor>, got "${osVersionArg}"`,
+    )
+    rnxExit(1)
+  }
 
   // --viewport <WxH> sizes the driver-launched page explicitly (film and
   // promo captures frame the 3d stage in landscape). takes precedence over
@@ -1527,7 +1619,9 @@ export async function runOpenCommand(
   const viewportArg = args.find((_, i) => args[i - 1] === '--viewport')
   const viewportMatch = viewportArg ? /^(\d+)x(\d+)$/.exec(viewportArg) : null
   if (viewportArg && !viewportMatch) {
-    console.error(`  peach open: --viewport must be <width>x<height>, got "${viewportArg}"`)
+    console.error(
+      `  peach open: --viewport must be <width>x<height>, got "${viewportArg}"`,
+    )
     rnxExit(1)
   }
   const explicitViewport = viewportMatch
@@ -1537,6 +1631,8 @@ export async function runOpenCommand(
   const buildShellUrlOpts: BuildShellUrlOptions = {
     hot: hotMode,
     device: deviceArg,
+    posture: postureArg,
+    osVersion: osVersionArg,
     resolvedBundle,
     project,
     proof: args.includes('--proof'),
@@ -1713,6 +1809,7 @@ export async function runOpenCommand(
           quiet,
         )
         await maybeDescribeAfterOpen(parsed.wsPort, targetSim.id, args)
+        printAgentListenHint(quiet)
         return { simId: targetSim.id, launched: false }
       }
     } finally {
@@ -1752,8 +1849,8 @@ export async function runOpenCommand(
     ownerPid,
     viewport:
       explicitViewport ??
-      (deviceSpec
-        ? { width: deviceSpec.width + 120, height: deviceSpec.height + 60 }
+      (deviceFitBox
+        ? { width: deviceFitBox.width + 120, height: deviceFitBox.height + 60 }
         : undefined),
     connectTimeoutMs: connectWait.hostTimeoutMs,
   })
@@ -1791,6 +1888,7 @@ export async function runOpenCommand(
   signalDriverLaunchConnected(result)
   printOpenedSim(openUrl, match, `${driver.name} driver`, quiet)
   await maybeDescribeAfterOpen(parsed.wsPort, match.id, args)
+  printAgentListenHint(quiet)
   return { simId: match.id, launched: true }
 }
 
@@ -1859,10 +1957,6 @@ export async function runUseCommand(args: string[], opts: ControlCommandOptions
   await runUseLikeCommand(args, opts)
 }
 
-export async function runFocusCommand(args: string[], opts: ControlCommandOptions = {}) {
-  await runUseLikeCommand(args, opts)
-}
-
 export async function runClaimCommand(args: string[], opts: ControlCommandOptions = {}) {
   const parsed = parseBridgeCliArgs(args, {
     port: opts.port,

package/cli/commands/cpu-profile.ts

@@ -30,6 +30,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { WebSocket } from 'ws'
 import { getCliVersion } from '../../src/cli-version'
+import { sleep } from '../../src/sleep'
 import { IS_STANDALONE } from '../standalone'
 
 interface ProfileOptions {
@@ -37,8 +38,6 @@ interface ProfileOptions {
   verbose?: boolean
 }
 
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
-
 // compact CDP client with flatten-mode sessionId routing — one ws to the page
 // target carries the page session plus every auto-attached worker session.
 class Cdp {
@@ -495,6 +494,7 @@ export async function runCpuProfile(
         const gate = new Promise((resolve) => {
           releaseGate = resolve
         })
+        Reflect.set(globalThis, '__sootsimCpuProfileCaptureComplete', false)
         Reflect.set(globalThis, '__sootsimCpuProfileBarrierState', state)
         Reflect.set(globalThis, '__sootsimCpuProfileBarrier', async (marker) => {
           if (state.marker === null) {
@@ -714,14 +714,23 @@ export async function runCpuProfile(
     )
     // querying the page while five high-frequency profilers are still active
     // can itself time out and lengthen the requested sampling interval. stop
-    // first, then read the already-recorded workload completion evidence.
-    const workloadEvidence = interactionBarrierEnabled
-      ? readCpuProfileWorkloadEvidence(
-          await evaluatePage(
-            `Reflect.get(globalThis, '__sootsimInteractionPartialResult') ?? null`,
-          ),
-        )
-      : null
+    // first, then read the already-recorded workload completion evidence. a
+    // failed read must not skip the profile/manifest writes below: the
+    // captured profiles are preserved and the manifest records the explicit
+    // evidence error, which already forces complete:false downstream.
+    let workloadEvidence: CpuProfileWorkloadEvidence | null = null
+    let workloadEvidenceError: string | null = null
+    try {
+      workloadEvidence = interactionBarrierEnabled
+        ? readCpuProfileWorkloadEvidence(
+            await evaluatePage(
+              `Reflect.get(globalThis, '__sootsimInteractionPartialResult') ?? null`,
+            ),
+          )
+        : null
+    } catch (error) {
+      workloadEvidenceError = error instanceof Error ? error.message : String(error)
+    }
     const workloadActionEpochMs =
       workloadEvidence?.captures.map((capture) => capture.actionEpochMs) ?? []
 
@@ -835,6 +844,7 @@ export async function runCpuProfile(
           captureWindowEndedAt: new Date(captureWindowEndedAtEpochMs).toISOString(),
           interactionBarrier,
           workloadEvidence,
+          workloadEvidenceError,
           workloadActionEpochMs,
           manifest,
         },
@@ -857,6 +867,9 @@ export async function runCpuProfile(
     return complete ? 0 : 1
   } finally {
     if (interactionBarrierInstalled) {
+      await evaluatePage(
+        `Reflect.set(globalThis, '__sootsimCpuProfileCaptureComplete', true)`,
+      ).catch(() => {})
       await releaseInteractionBarrier('cleanup').catch(() => {})
     }
     cdp.close()

package/cli/commands/daemon.ts

@@ -36,6 +36,7 @@ import {
 } from '../../src/home-paths'
 import { rnxPublicBrand } from '../../src/public-brand'
 import { printCommandHelp } from '../help'
+import { escapeXml } from '../maestro-report'
 import { rnxExit } from '../run-rnx'
 import { rnxSelfInvocation, type RnxSelfInvocation } from '../self-invocation'
 import { ensureDaemonApp } from './daemon-mac-app'
@@ -167,15 +168,6 @@ WantedBy=default.target
 `
 }
 
-function escapeXml(value: string): string {
-  return value
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;')
-}
-
 function shellQuote(value: string): string {
   return /[^\w@%+=:,./-]/.test(value) ? `'${value.replace(/'/g, `'\\''`)}'` : value
 }

package/cli/commands/detox.ts

@@ -198,21 +198,28 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
     jestArgs.push('--config', tempConfig)
   }
 
-  // hosted run registration (org dashboard pass/fail row). when it applies,
-  // capture jest's structured results via --json --outputFile so the row can
-  // carry test counts + the first failure; console output stays untouched.
+  // proof runs need the test count too: jest exits zero when a name filter
+  // skips every test, which would otherwise report an empty proof as passing.
+  const proofCapture =
+    process.env.CONFORMANCE_PROOF === '1' ||
+    !!process.env.CONFORMANCE_PROOF_DIR ||
+    process.env.CONFORMANCE_TARGET === 'sootsim'
+
+  // hosted run registration (org dashboard pass/fail row) also uses jest's
+  // structured results for test counts and the first failure.
   const auth = resolveCliAuth()
   const wantsRegistration =
     !watch &&
     (process.env.PEACH_REQUIRE_REGISTRATION === 'true' ||
       shouldRegisterRun({ uploadedShare: false, auth }))
+  const needsResults = !watch && (proofCapture || wantsRegistration)
   let resultsFile: string | null =
     getFlag('--outputFile') || process.env.SOOTSIM_JEST_OUTPUT_FILE || null
-  if ((process.env.SOOTSIM_JEST_JSON === '1' || wantsRegistration) && !hasFlag('--json'))
+  if ((process.env.SOOTSIM_JEST_JSON === '1' || needsResults) && !hasFlag('--json'))
     jestArgs.push('--json')
   if (!getFlag('--outputFile') && process.env.SOOTSIM_JEST_OUTPUT_FILE) {
     jestArgs.push('--outputFile', process.env.SOOTSIM_JEST_OUTPUT_FILE)
-  } else if (!resultsFile && wantsRegistration) {
+  } else if (!resultsFile && needsResults) {
     resultsFile = join(tmpdir(), `rnx-detox-results-${process.pid}.json`)
     jestArgs.push('--outputFile', resultsFile)
   }
@@ -235,10 +242,6 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
   // then visits as tagged heap pointers. disable both Maglev and Sparkplug so
   // execution stays on the stable Ignition + TurboFan pipeline under Node 24.
   // normal user detox runs retain their node defaults and resolve jest through npx.
-  const proofCapture =
-    process.env.CONFORMANCE_PROOF === '1' ||
-    !!process.env.CONFORMANCE_PROOF_DIR ||
-    process.env.CONFORMANCE_TARGET === 'sootsim'
   const command = proofCapture ? 'node' : 'npx'
   const commandArgs = proofCapture
     ? [
@@ -294,16 +297,21 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
     if (tempConfig) unlinkSync(tempConfig)
   }
 
+  const results =
+    resultsFile && existsSync(resultsFile) && statSync(resultsFile).mtimeMs >= startedAt
+      ? readJestResults(resultsFile)
+      : null
+  // a selection that skipped every test is not a passing suite. a proof run
+  // without structured results has no test-count verdict either.
+  if (code === 0 && results?.numPassedTests === 0) {
+    console.error('  error: no tests were selected or executed')
+    code = 1
+  } else if (code === 0 && proofCapture && !watch && !results) {
+    console.error('  error: jest did not report test results')
+    code = 1
+  }
+
   if (wantsRegistration) {
-    const results =
-      resultsFile && existsSync(resultsFile) && statSync(resultsFile).mtimeMs >= startedAt
-        ? readJestResults(resultsFile)
-        : null
-    // a selection that skipped every test is not a passing suite.
-    if (code === 0 && results && results.numPassedTests === 0) {
-      console.error('  error: no tests were selected or executed')
-      code = 1
-    }
     const origin = await resolveDefaultUploadOrigin()
     const run = await registerRun({
       origin,

package/cli/commands/device.ts

@@ -1,13 +1,17 @@
 import {
   devices,
+  DUO_REST_PROGRESS,
   getDevice,
   listSelectableDeviceModels,
   type DeviceModel,
+  type DuoFoldRest,
 } from 'peach-engine/settings'
+import { SOOTSIM_SHELL_COMMAND_NAME } from '../../src/menu'
 import { rnxExit } from '../run-rnx'
 import {
   callInBridge,
   createBridgeFromParsed,
+  evalInBridge,
   parseBridgeCliArgs,
   type ParsedBridgeCliArgs,
 } from '../ws-bridge'
@@ -33,11 +37,14 @@ usage:
   peach device get
   peach device set <model> [--sim <id>]
   peach device list
+  peach device posture [closed|book|open|laptop|tent|toggle] [--sim <id>]
 
 examples:
   peach device
   peach device set iphone-16
   peach device set iphone-16-pro-max --sim a7
+  peach device posture open
+  peach device posture laptop
 `)
 }
 
@@ -59,7 +66,16 @@ async function readCurrentDevice(
     )) ?? { deviceModel: null }
     const model = typeof settings.deviceModel === 'string' ? settings.deviceModel : null
     if (!model || !(model in devices)) return null
-    const spec = getDevice(model as DeviceModel)
+    const spec = getDevice(
+      model as DeviceModel,
+      settings.posture === 'open' || settings.posture === 'closed'
+        ? settings.posture
+        : undefined,
+      settings.orientation === 'portrait' || settings.orientation === 'landscape'
+        ? settings.orientation
+        : undefined,
+      settings.landscapeSide === 'right' ? 'right' : 'left',
+    )
     return {
       model,
       width: spec.width,
@@ -72,6 +88,37 @@ async function readCurrentDevice(
   }
 }
 
+function isDuoRest(value: unknown): value is DuoFoldRest {
+  return typeof value === 'string' && value in DUO_REST_PROGRESS
+}
+
+const DUO_RESTS = Object.keys(DUO_REST_PROGRESS).filter(isDuoRest)
+
+type CurrentPostureSnapshot = {
+  model: DeviceModel
+  rest: DuoFoldRest | null
+} | null
+
+// the binary display posture cannot name laptop, book, or tent. only the fold
+// bus names the rest; it is null while a drag holds the hinge between rests.
+async function readCurrentPosture(
+  parsed: ParsedBridgeCliArgs,
+): Promise<CurrentPostureSnapshot> {
+  const bridge = createBridgeFromParsed(parsed)
+  try {
+    const settings = (await callInBridge<Record<string, unknown> | null>(
+      bridge,
+      'SootSim.bridges.settings.get',
+    )) ?? { deviceModel: null }
+    const model = typeof settings.deviceModel === 'string' ? settings.deviceModel : null
+    if (!model || !(model in devices)) return null
+    const rest = await evalInBridge(bridge, 'globalThis.__sootsimDuoFold?.rest ?? null')
+    return { model: model as DeviceModel, rest: isDuoRest(rest) ? rest : null }
+  } finally {
+    bridge.close()
+  }
+}
+
 export async function runDeviceCommand(args: string[], opts: DeviceCommandOptions) {
   if (args.includes('--help') || args.includes('-h')) {
     usage()
@@ -128,6 +175,87 @@ export async function runDeviceCommand(args: string[], opts: DeviceCommandOption
     return
   }
 
+  if (subcommand === 'posture') {
+    const parsed = parseBridgeCliArgs(args, { port: opts.port })
+    // the want is optional, so read it past the bridge flags: raw args[1]
+    // would take --sim as the want on a bare `posture --sim <id>` read.
+    const raw = parsed.positional[1]
+    const want = raw === undefined || raw === 'toggle' || isDuoRest(raw) ? raw : null
+    if (want === null) {
+      console.error(`  error: device posture expects ${DUO_RESTS.join(', ')}, or toggle`)
+      rnxExit(1)
+    }
+    const current = await readCurrentPosture(parsed)
+    if (!current) {
+      console.error('  error: could not read current posture from the target sim')
+      rnxExit(1)
+    }
+    if (!devices[current.model].supportedPostures) {
+      console.error(
+        `  error: ${current.model} has a single posture — fold posture is only available on iphone-duo`,
+      )
+      rnxExit(1)
+    }
+    if (!want) {
+      if (!current.rest) {
+        console.error(
+          '  error: the Duo fold has no current rest; choose a posture explicitly',
+        )
+        rnxExit(1)
+      }
+      console.log(`  ${current.rest} (${current.model})`)
+      return
+    }
+    if (want === 'toggle' && !current.rest) {
+      console.error(
+        '  error: the Duo fold has no current rest; choose a posture explicitly',
+      )
+      rnxExit(1)
+    }
+    const target: DuoFoldRest =
+      want === 'toggle' ? (current.rest === 'closed' ? 'open' : 'closed') : want
+    if (target === current.rest) {
+      console.log(`  kept posture: ${current.rest} (${current.model})`)
+      return
+    }
+    const bridge = createBridgeFromParsed(parsed)
+    try {
+      // the typed command the duo's pose buttons dispatch: the fold engine
+      // sweeps the hinge there, turning the body for laptop and tent, so the
+      // app sees the same fold and reserved regions as from the rail. the
+      // command resolves once the fold bus reports the hinge resting there.
+      const settled = await evalInBridge<boolean>(
+        bridge,
+        `new Promise((resolve) => {
+          const deadline = Date.now() + 10000
+          const settled = () => {
+            const fold = globalThis.__sootsimDuoFold
+            return !!fold && fold.rest === ${JSON.stringify(target)} && !fold.active &&
+              Math.abs(fold.progress - ${DUO_REST_PROGRESS[target]}) < 1e-6
+          }
+          const check = () => {
+            if (settled()) resolve(true)
+            else if (Date.now() > deadline) resolve(false)
+            else setTimeout(check, 50)
+          }
+          window.dispatchEvent(new CustomEvent(${JSON.stringify(SOOTSIM_SHELL_COMMAND_NAME)}, { detail: { type: 'fold-to-rest', rest: ${JSON.stringify(target)} } }))
+          check()
+        })`,
+        { acquireLock: true },
+      )
+      if (!settled) {
+        console.error(
+          `  error: the fold did not come to rest at ${target} within 10s (${current.model})`,
+        )
+        rnxExit(1)
+      }
+      console.log(`  set posture: ${target} (${current.model})`)
+    } finally {
+      bridge.close()
+    }
+    return
+  }
+
   usage()
   console.error(`  unknown subcommand: ${subcommand}`)
   rnxExit(1)