native-sim 0.1.0

package/templates/native-sim.yml

@@ -0,0 +1,654 @@
+# native-sim-template-version: 18
+# Generated by `native-sim init`. Boots an iOS Simulator on a GitHub-hosted macOS
+# runner, builds this Expo app into it, and streams it back over a tunnel using
+# @expo/serve-sim. The tunnel URL is published as a commit status, which is the
+# only GitHub surface readable *while* the job is still running.
+name: native-sim
+run-name: native-sim ${{ inputs.session }} · ${{ inputs.mode }} · ${{ inputs.minutes }}m
+
+on:
+  workflow_dispatch:
+    inputs:
+      session:
+        description: Session id (used to correlate the run with the local CLI)
+        required: true
+      gate_token:
+        description: Shared secret required to view the stream
+        required: true
+      minutes:
+        description: How long to hold the stream open
+        default: "30"
+      device:
+        description: Simulator device name
+        default: iPhone 17 Pro
+      mode:
+        description: build (compile from source), app (install a prebuilt .app), or go (Expo Go)
+        default: build
+      app_url:
+        description: URL of a prebuilt simulator .app archive (mode:app)
+        default: ""
+      app_release_asset:
+        description: >-
+          Asset name on this repo's `native-sim-build` release to install
+          (mode:app). Fetched with the job's own GITHUB_TOKEN, so a private repo
+          needs no extra credentials and nothing is publicly downloadable.
+        default: ""
+      transport:
+        description: >-
+          http (default) or webrtc. webrtc needs a TURN relay, which is a paid,
+          per-GB service, and measured no better than http here — opt in only.
+        default: http
+      codec:
+        description: HTTP stream codec. h264 serves /stream.avcc, which emits nothing on
+          GitHub runners; mjpeg is what actually streams.
+        default: mjpeg
+      max_dimension:
+        description: Cap the captured width/height in pixels; 0 keeps native resolution.
+          640 was measurably snappier but visibly soft on a retina display, where the
+          preview is drawn at ~2x CSS pixels. 900 keeps it sharp.
+        default: "900"
+      video_fps:
+        description: MJPEG frame rate. serve-sim defaults to 60, which over a tunnel
+          stutters more than a reliably delivered 30 and doubles encode CPU.
+        default: "30"
+      video_quality:
+        description: MJPEG quality 0.05-1. Lower means fewer bytes per frame, but it shows
+          as compression artefacts rather than softness — reduce fps or dimension first.
+        default: "0.7"
+      export_app:
+        description: Upload the built .app as an artifact so it can be downloaded
+        default: "false"
+      agent_device:
+        description: >-
+          Also run an agent-device proxy beside the simulator, reachable at
+          <url>/agent-device, so a coding agent on your machine can drive the app.
+        default: "false"
+      agent_device_version:
+        description: agent-device version to install. Pin it — the client and the
+          proxied daemon should match.
+        default: 0.20.1
+      scheme:
+        description: Xcode scheme (defaults to the generated workspace name)
+        default: ""
+      cache:
+        description: Reuse a fingerprint-matched .app instead of rebuilding natively
+        default: "true"
+      runner:
+        description: Runner label (must be arm64 — serve-sim ships arm64-only binaries)
+        default: macos-26
+
+permissions:
+  contents: read
+  statuses: write
+
+concurrency:
+  group: native-sim-${{ inputs.session }}
+  cancel-in-progress: true
+
+jobs:
+  stream:
+    runs-on: ${{ inputs.runner }}
+    # GitHub caps hosted jobs at 6h; the hold step ends the session earlier.
+    timeout-minutes: 360
+    env:
+      GH_TOKEN: ${{ github.token }}
+      STATUS_CONTEXT: native-sim/${{ inputs.session }}
+      GATE_PORT: "3199"
+      PREVIEW_PORT: "3200"
+      AGENT_PORT: "4310"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Cache npm + CocoaPods
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            ~/Library/Caches/CocoaPods
+          key: native-sim-${{ runner.os }}-${{ hashFiles('**/package-lock.json', '**/yarn.lock', '**/pnpm-lock.yaml') }}
+          restore-keys: native-sim-${{ runner.os }}-
+
+      - name: Install JS dependencies
+        timeout-minutes: 20
+        if: inputs.mode != 'app'
+        run: |
+          set -euo pipefail
+          if [ -f pnpm-lock.yaml ]; then
+            corepack enable && pnpm install --frozen-lockfile
+          elif [ -f yarn.lock ]; then
+            corepack enable
+            # --immutable is Yarn 2+; Yarn 1 wants --frozen-lockfile.
+            yarn install --immutable || yarn install --frozen-lockfile
+          elif [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+
+      - name: Fingerprint native build inputs
+        id: fp
+        if: inputs.mode == 'build' && inputs.cache == 'true'
+        timeout-minutes: 5
+        run: |
+          set -euo pipefail
+          # @expo/fingerprint hashes exactly the inputs that affect the *native*
+          # build (dependencies, config plugins, native dirs) and deliberately
+          # ignores application JS, so a JS-only change still hits the cache.
+          HASH=$(npx --yes @expo/fingerprint fingerprint:generate --platform ios \
+            | node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(0,"utf8")).hash)')
+          echo "hash=$HASH" >> "$GITHUB_OUTPUT"
+          echo "native fingerprint: $HASH"
+
+      - name: Restore cached app build
+        id: appcache
+        if: inputs.mode == 'build' && inputs.cache == 'true'
+        uses: actions/cache/restore@v4
+        with:
+          path: build/native-sim-app
+          key: native-sim-app-${{ runner.os }}-${{ steps.fp.outputs.hash }}
+
+      - name: Boot simulator
+        timeout-minutes: 10
+        id: sim
+        run: |
+          set -euo pipefail
+          DEVICE='${{ inputs.device }}'
+
+          UDID=$(xcrun simctl list devices available \
+            | grep -F "$DEVICE (" \
+            | head -1 \
+            | sed -E 's/.*\(([0-9A-Fa-f-]{36})\).*/\1/' || true)
+
+          if [ -z "$UDID" ]; then
+            echo "::warning::'$DEVICE' not available on this image; falling back to the newest available iPhone"
+            UDID=$(xcrun simctl list devices available \
+              | grep -E '^\s+iPhone' \
+              | tail -1 \
+              | sed -E 's/.*\(([0-9A-Fa-f-]{36})\).*/\1/')
+          fi
+
+          [ -n "$UDID" ] || { echo "No iOS simulator available on this runner image"; exit 1; }
+
+          xcrun simctl boot "$UDID" || true
+          xcrun simctl bootstatus "$UDID" -b
+          echo "udid=$UDID" >> "$GITHUB_OUTPUT"
+          xcrun simctl list devices | grep -F "$UDID"
+
+      - name: Start serve-sim
+        timeout-minutes: 10
+        env:
+          TURN_KEY_ID: ${{ secrets.NATIVE_SIM_TURN_KEY_ID }}
+          TURN_KEY_TOKEN: ${{ secrets.NATIVE_SIM_TURN_KEY_TOKEN }}
+          TURN_URL: ${{ secrets.NATIVE_SIM_TURN_URL }}
+          TURN_USERNAME: ${{ secrets.NATIVE_SIM_TURN_USERNAME }}
+          TURN_CREDENTIAL: ${{ secrets.NATIVE_SIM_TURN_CREDENTIAL }}
+          STUN_URL: ${{ secrets.NATIVE_SIM_STUN_URL }}
+        run: |
+          set -euo pipefail
+          # MJPEG re-sends a whole JPEG per frame; h264 encodes only what changed,
+          # which is the difference between a choppy and a smooth tunnel stream.
+          # max-dimension cuts pixels quadratically, saving encode CPU and bytes.
+          ARGS=(
+            --detach --quiet
+            --port "$PREVIEW_PORT"
+            --max-dimension '${{ inputs.max_dimension }}'
+            --video-fps '${{ inputs.video_fps }}'
+          )
+
+          if [ '${{ inputs.transport }}' = 'webrtc' ] && [ -n "$TURN_KEY_ID" ]; then
+            # Cloudflare Realtime mints short-lived TURN credentials, so nothing
+            # long-lived is stored and a leak expires on its own.
+            echo "Minting TURN credentials from Cloudflare Realtime"
+            RESP=$(curl -fsS --retry 2 \
+              "https://rtc.live.cloudflare.com/v1/turn/keys/$TURN_KEY_ID/credentials/generate-ice-servers" \
+              -H "Authorization: Bearer $TURN_KEY_TOKEN" \
+              -H 'Content-Type: application/json' \
+              --data '{"ttl": 7200}')
+
+            # iceServers is an ARRAY: entries without a username are STUN, the
+            # entry carrying username/credential holds the TURN urls.
+            parse() {
+              printf '%s' "$RESP" | node -e '
+                let s = "";
+                process.stdin.on("data", (d) => (s += d)).on("end", () => {
+                  const list = JSON.parse(s).iceServers || [];
+                  const turn = list.find((e) => e.username) || {};
+                  const stun = list.filter((e) => !e.username).flatMap((e) => [].concat(e.urls || []));
+                  const out = {
+                    urls: [].concat(turn.urls || []).join(","),
+                    username: turn.username || "",
+                    credential: turn.credential || "",
+                    stun: stun.join(","),
+                  };
+                  process.stdout.write(out[process.argv[1]] || "");
+                });
+              ' "$1"
+            }
+
+            TURN_URL=$(parse urls)
+            TURN_USERNAME=$(parse username)
+            TURN_CREDENTIAL=$(parse credential)
+            STUN_URL=$(parse stun)
+
+            # Mask before anything else can echo them.
+            echo "::add-mask::$TURN_CREDENTIAL"
+            echo "::add-mask::$TURN_USERNAME"
+            [ -n "$TURN_URL" ] || { echo "::error::Realtime returned no TURN urls"; exit 1; }
+            echo "TURN ready: $(printf '%s' "$TURN_URL" | tr ',' '\n' | wc -l | tr -d ' ') relay url(s), $(printf '%s' "$STUN_URL" | tr ',' '\n' | wc -l | tr -d ' ') stun"
+          fi
+
+          if [ '${{ inputs.transport }}' = 'webrtc' ]; then
+            # WebRTC adapts bitrate under congestion instead of dropping frames,
+            # but a quick tunnel carries no UDP, so TURN is mandatory - STUN alone
+            # cannot traverse it. Credentials come from repo secrets, never from
+            # workflow inputs, which are visible to anyone who can read the repo.
+            [ -n "$TURN_URL" ] || { echo "::error::transport webrtc needs NATIVE_SIM_TURN_URL"; exit 1; }
+            ARGS+=(--transport webrtc --webrtc-codec h264 --turn-url "$TURN_URL")
+            [ -n "$TURN_USERNAME" ]   && ARGS+=(--turn-username "$TURN_USERNAME")
+            [ -n "$TURN_CREDENTIAL" ] && ARGS+=(--turn-credential "$TURN_CREDENTIAL")
+            [ -n "$STUN_URL" ]        && ARGS+=(--stun-url "$STUN_URL")
+          else
+            # These target MJPEG explicitly: --video-fps only sets h264Fps, and the
+            # h264/AVCC path emits no data on GitHub's macOS runners.
+            ARGS+=(
+              --codec '${{ inputs.codec }}'
+              --mjpeg-fps '${{ inputs.video_fps }}'
+              --mjpeg-quality '${{ inputs.video_quality }}'
+            )
+          fi
+
+          npx --yes @expo/serve-sim@latest "${ARGS[@]}" | tee serve-sim.json
+
+          # /readyz blocks until the simulator and the native capture session are up.
+          for _ in $(seq 1 90); do
+            if curl -fsS "http://127.0.0.1:$PREVIEW_PORT/readyz" >/dev/null 2>&1; then
+              echo "serve-sim ready"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "serve-sim never became ready"
+          curl -sS "http://127.0.0.1:$PREVIEW_PORT/healthz" || true
+          exit 1
+
+      - name: Start auth gate
+        timeout-minutes: 5
+        env:
+          NATIVE_SIM_GATE_TOKEN: ${{ inputs.gate_token }}
+          # Empty disables the /agent-device route outright, so a session started
+          # without --agent exposes no control surface beyond the stream.
+          NATIVE_SIM_AGENT_PORT: ${{ inputs.agent_device == 'true' && '4310' || '' }}
+        run: |
+          set -euo pipefail
+          # serve-sim has no auth of its own, so nothing but this gate stands
+          # between a leaked tunnel URL and full control of the simulator.
+          # The gate starts before the agent-device proxy does; until that comes
+          # up, /agent-device/* simply 502s.
+          NATIVE_SIM_TARGET_PORT="$PREVIEW_PORT" NATIVE_SIM_GATE_PORT="$GATE_PORT" \
+            nohup node .github/native-sim/gate.cjs > gate.log 2>&1 &
+          disown
+          for _ in $(seq 1 30); do
+            curl -fsS -o /dev/null "http://127.0.0.1:$GATE_PORT/__native-sim/healthz" && exit 0
+            sleep 1
+          done
+          cat gate.log; exit 1
+
+      - name: Open tunnel and publish URL
+        timeout-minutes: 10
+        id: tunnel
+        env:
+          GATE_TOKEN: ${{ inputs.gate_token }}
+        run: |
+          set -euo pipefail
+          curl -fsSL -o cloudflared.tgz \
+            https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-arm64.tgz
+          tar -xzf cloudflared.tgz
+          chmod +x cloudflared
+
+          nohup ./cloudflared tunnel --no-autoupdate --url "http://127.0.0.1:$GATE_PORT" \
+            --logfile cloudflared.log > /dev/null 2>&1 &
+          disown
+
+          TUNNEL=""
+          for _ in $(seq 1 60); do
+            TUNNEL=$(grep -Eo 'https://[a-z0-9-]+\.trycloudflare\.com' cloudflared.log 2>/dev/null | head -1 || true)
+            [ -n "$TUNNEL" ] && break
+            sleep 2
+          done
+          [ -n "$TUNNEL" ] || { echo "cloudflared never reported a URL"; tail -50 cloudflared.log; exit 1; }
+
+          URL="$TUNNEL/?k=$GATE_TOKEN"
+          echo "url=$URL" >> "$GITHUB_OUTPUT"
+
+          # Commit statuses are world-readable on a public repo, so publish the
+          # bare tunnel URL only. The CLI generated the access key and appends it
+          # locally; putting it here would hand anyone a working link.
+
+          # A commit status is the one channel the local CLI can read live.
+          gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" \
+            -f state=success \
+            -f "context=$STATUS_CONTEXT" \
+            -f "target_url=$TUNNEL" \
+            -f "description=simulator live; app still building"
+
+          echo "::notice title=native-sim::$TUNNEL (append the access key the CLI printed)"
+          {
+            echo "## 📱 native-sim"
+            echo
+            echo "Simulator live for ${{ inputs.minutes }} minutes at \`$TUNNEL\`."
+            echo
+            echo "The access key is deliberately not published here — use the full"
+            echo "URL the CLI printed. Anyone holding it can drive the simulator."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Build app
+        timeout-minutes: 60
+        if: inputs.mode == 'build' && steps.appcache.outputs.cache-hit != 'true'
+        env:
+          UDID: ${{ steps.sim.outputs.udid }}
+        run: |
+          set -euo pipefail
+          # Dependencies are already installed above, so skip prebuild's own install pass.
+          npx expo prebuild --platform ios --no-install
+          npx pod-install ios
+
+          WORKSPACE=$(find ios -maxdepth 1 -name '*.xcworkspace' | head -1)
+          [ -n "$WORKSPACE" ] || { echo "expo prebuild produced no .xcworkspace"; exit 1; }
+
+          SCHEME='${{ inputs.scheme }}'
+          [ -n "$SCHEME" ] || SCHEME=$(basename "$WORKSPACE" .xcworkspace)
+          echo "Building scheme '$SCHEME' from $WORKSPACE"
+
+          xcodebuild \
+            -workspace "$WORKSPACE" \
+            -scheme "$SCHEME" \
+            -configuration Release \
+            -sdk iphonesimulator \
+            -destination "id=$UDID" \
+            -derivedDataPath build/ios \
+            CODE_SIGNING_ALLOWED=NO \
+            -quiet \
+            build
+
+          APP=$(find build/ios/Build/Products/Release-iphonesimulator -maxdepth 1 -name '*.app' | head -1)
+          [ -n "$APP" ] || { echo "No .app produced"; exit 1; }
+
+          # Park the bundle where the cache (and the install step) expect it.
+          rm -rf build/native-sim-app
+          mkdir -p build/native-sim-app
+          cp -R "$APP" build/native-sim-app/
+
+      - name: Save app build to cache
+        if: inputs.mode == 'build' && inputs.cache == 'true' && steps.appcache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: build/native-sim-app
+          key: native-sim-app-${{ runner.os }}-${{ steps.fp.outputs.hash }}
+
+      - name: Export app archive
+        if: inputs.mode == 'build' && inputs.export_app == 'true'
+        run: |
+          set -euo pipefail
+          APP=$(find build/native-sim-app -maxdepth 1 -name '*.app' | head -1)
+          [ -n "$APP" ] || { echo "::error::nothing to export"; exit 1; }
+          # Tar it: upload-artifact zips its input, and a zipped .app directory
+          # loses the executable bits simctl needs.
+          tar -C build/native-sim-app -czf "build/$(basename "$APP").tar.gz" "$(basename "$APP")"
+          ls -lh build/*.tar.gz
+
+      - name: Upload app artifact
+        if: inputs.mode == 'build' && inputs.export_app == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: native-sim-app-${{ inputs.session }}
+          path: build/*.app.tar.gz
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Install and launch app
+        timeout-minutes: 15
+        if: inputs.mode == 'build'
+        env:
+          UDID: ${{ steps.sim.outputs.udid }}
+          CACHE_HIT: ${{ steps.appcache.outputs.cache-hit }}
+        run: |
+          set -euo pipefail
+          APP=$(find build/native-sim-app -maxdepth 1 -name '*.app' | head -1)
+          [ -n "$APP" ] || { echo "No .app to install"; exit 1; }
+
+          if [ "$CACHE_HIT" = "true" ]; then
+            # The fingerprint ignores app JS, so a reused binary carries a stale
+            # bundle. Re-embed current JS rather than rebuilding natively.
+            echo "Reused cached native build; refreshing the JS bundle"
+            npx expo export:embed \
+              --platform ios \
+              --dev false \
+              --bundle-output "$APP/main.jsbundle" \
+              --assets-dest "$APP"
+          fi
+
+          BUNDLE_ID=$(/usr/libexec/PlistBuddy -c 'Print CFBundleIdentifier' "$APP/Info.plist")
+          xcrun simctl install "$UDID" "$APP"
+          xcrun simctl launch "$UDID" "$BUNDLE_ID"
+          echo "Launched $BUNDLE_ID"
+
+      - name: Install prebuilt app
+        timeout-minutes: 15
+        if: inputs.mode == 'app'
+        env:
+          UDID: ${{ steps.sim.outputs.udid }}
+          APP_URL: ${{ inputs.app_url }}
+          APP_RELEASE_ASSET: ${{ inputs.app_release_asset }}
+          APP_RELEASE_TAG: native-sim-build
+        run: |
+          set -euo pipefail
+          [ -n "$APP_URL" ] || [ -n "$APP_RELEASE_ASSET" ] \
+            || { echo "::error::mode 'app' requires app_url or app_release_asset"; exit 1; }
+
+          mkdir -p build/prebuilt && cd build/prebuilt
+
+          if [ -n "$APP_RELEASE_ASSET" ]; then
+            # Hosted on this repo's own release. The job token is already scoped
+            # here, so a private repo costs no extra credential and a draft
+            # release is not downloadable by the public.
+            echo "Downloading $APP_RELEASE_ASSET from release $APP_RELEASE_TAG"
+            gh release download "$APP_RELEASE_TAG" \
+              --repo "$GITHUB_REPOSITORY" \
+              --pattern "$APP_RELEASE_ASSET" \
+              --output download.bin \
+              --clobber
+          else
+            echo "Downloading prebuilt app"
+            curl -fsSL --retry 3 -o download.bin "$APP_URL"
+          fi
+          file download.bin
+
+          # EAS simulator builds ship as .tar.gz; some tooling emits .zip.
+          case "$(file -b --mime-type download.bin)" in
+            application/gzip|application/x-gzip) tar -xzf download.bin ;;
+            application/zip)                     unzip -q download.bin ;;
+            *) echo "::error::unrecognised archive; expected .tar.gz or .zip of a simulator .app"; exit 1 ;;
+          esac
+
+          APP=$(find . -maxdepth 3 -type d -name '*.app' | head -1)
+          [ -n "$APP" ] || { echo "::error::no .app found in the archive"; exit 1; }
+
+          # A device .ipa cannot run on a simulator; catch that early with a clear message.
+          if [ ! -f "$APP/Info.plist" ]; then
+            echo "::error::$APP has no Info.plist — is this a simulator build?"; exit 1
+          fi
+          if ! /usr/libexec/PlistBuddy -c 'Print CFBundleSupportedPlatforms:0' "$APP/Info.plist" 2>/dev/null | grep -q Simulator; then
+            echo "::error::this build targets a device, not a simulator. Build with the EAS 'simulator' profile (ios.simulator: true)."
+            exit 1
+          fi
+
+          BUNDLE_ID=$(/usr/libexec/PlistBuddy -c 'Print CFBundleIdentifier' "$APP/Info.plist")
+          xcrun simctl install "$UDID" "$APP"
+          xcrun simctl launch "$UDID" "$BUNDLE_ID"
+          echo "Launched $BUNDLE_ID from prebuilt archive"
+
+      - name: Start Expo Go
+        timeout-minutes: 15
+        if: inputs.mode == 'go'
+        run: |
+          set -euo pipefail
+          # `expo start --ios` targets the already-booted simulator and installs
+          # Expo Go itself. Metro stays local to the runner.
+          CI=1 nohup npx expo start --ios > expo-start.log 2>&1 &
+          disown
+          for _ in $(seq 1 60); do
+            curl -fsS http://127.0.0.1:8081/status >/dev/null 2>&1 && break
+            sleep 2
+          done
+          tail -20 expo-start.log || true
+
+      - name: Report app installed
+        if: inputs.mode == 'build' || inputs.mode == 'app'
+        run: |
+          gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" \
+            -f state=success \
+            -f "context=$STATUS_CONTEXT" \
+            -f "description=app installed and running" || true
+
+      - name: Install agent-device
+        id: ad
+        if: inputs.agent_device == 'true'
+        timeout-minutes: 10
+        run: |
+          set -euo pipefail
+          npm install -g "agent-device@${{ inputs.agent_device_version }}"
+          agent-device --version
+          # The runner cache key has to pin the Xcode version too: an XCTest
+          # runner built against a different Xcode is not reusable.
+          echo "xcode=$(xcodebuild -version | head -1 | tr ' ' '-')" >> "$GITHUB_OUTPUT"
+
+      - name: Cache agent-device XCTest runner
+        if: inputs.agent_device == 'true'
+        uses: actions/cache@v4
+        with:
+          path: ~/.agent-device/apple-runner/derived
+          # Exact key, no restore-keys: agent-device documents that broad
+          # fallbacks hand back a runner built for another toolchain, which is
+          # worse than building one from scratch.
+          key: agent-device-runner-${{ runner.os }}-${{ inputs.agent_device_version }}-${{ steps.ad.outputs.xcode }}
+
+      - name: Start agent-device proxy
+        if: inputs.agent_device == 'true'
+        timeout-minutes: 15
+        env:
+          GATE_TOKEN: ${{ inputs.gate_token }}
+          # Both default to 300000ms, so the daemon and the XCTest runner are
+          # reaped five minutes after the last command — measured here as a
+          # session that was healthy at 13:32:36 and gone by 13:37:44, before
+          # the agent ever issued its first command. Health probes do not count
+          # as activity. 0 means "run until killed", which is right for native-sim:
+          # the hold loop *is* the session and the VM is destroyed with it, so
+          # there is nothing to leak by staying up.
+          AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS: "0"
+          AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS: "0"
+          # A second, independent timer: the *device lease* taken by `open`
+          # expires after five minutes without commands, and every later command
+          # then fails UNAUTHORIZED ("Lease does not match session owner"). That
+          # default protects a shared Mac from an agent that wandered off; here
+          # the device is single-tenant and dies with the VM, so hold the lease
+          # for the job cap instead. Max must move too, or it clamps the default.
+          AGENT_DEVICE_LEASE_TTL_MS: "21600000"
+          AGENT_DEVICE_LEASE_MAX_TTL_MS: "21600000"
+        run: |
+          set -euo pipefail
+          # `proxy` serves the daemon HTTP contract under /agent-device/*, which
+          # is the base path `connect proxy` expects behind a shared origin — so
+          # it rides the tunnel that is already open instead of needing its own.
+          # It reuses the gate token: one secret covers both stream and control.
+          nohup agent-device proxy --host 127.0.0.1 --port "$AGENT_PORT" \
+            --daemon-auth-token "$GATE_TOKEN" > agent-device-proxy.log 2>&1 &
+          disown
+
+          for _ in $(seq 1 60); do
+            curl -fsS -o /dev/null "http://127.0.0.1:$AGENT_PORT/health" && break
+            sleep 1
+          done
+          curl -fsS "http://127.0.0.1:$AGENT_PORT/health" \
+            || { echo "::error::agent-device proxy never became healthy"; cat agent-device-proxy.log; exit 1; }
+          echo "agent-device proxy listening on 127.0.0.1:$AGENT_PORT"
+
+          # Apple CI wants the XCTest runner built before the first interaction,
+          # or the agent's opening snapshot pays several minutes of setup. Run it
+          # against the daemon the proxy already started (`proxy` starts *or
+          # reuses* one) so no second daemon holds a competing runner lease.
+          # 240000 was too tight: a cold build measured 3m40s on one runner and
+          # blew past 4 minutes on the next. On timeout agent-device kills the
+          # xcodebuild it started, and that takes the daemon down with it — so a
+          # tight timeout does not degrade gracefully, it removes the whole
+          # agent surface. Give a cold build real room; a cache hit returns in
+          # seconds regardless.
+          if agent-device prepare ios-runner --platform ios --timeout 900000; then
+            echo "XCTest runner ready"
+          else
+            echo "::warning::prepare ios-runner failed — the supervisor below will restart the daemon"
+            tail -40 agent-device-proxy.log || true
+          fi
+
+      - name: Hold the stream open
+        env:
+          AGENT_ENABLED: ${{ inputs.agent_device }}
+          GATE_TOKEN: ${{ inputs.gate_token }}
+          AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS: "0"
+          AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS: "0"
+          AGENT_DEVICE_LEASE_TTL_MS: "21600000"
+          AGENT_DEVICE_LEASE_MAX_TTL_MS: "21600000"
+        run: |
+          set -uo pipefail
+          MINUTES=${{ inputs.minutes }}
+          [ "$MINUTES" -le 350 ] || MINUTES=350
+          END=$(( $(date +%s) + MINUTES * 60 ))
+          AGENT_LAST_RESTART=0
+
+          echo "Streaming until $(date -r "$END")"
+          while [ "$(date +%s)" -lt "$END" ]; do
+            if ! curl -fsS -o /dev/null "http://127.0.0.1:$PREVIEW_PORT/healthz"; then
+              echo "::error::serve-sim stopped responding"
+              exit 1
+            fi
+            # A dead agent proxy is not worth tearing down a working stream for,
+            # but it should not fail silently either — the agent would just see
+            # its next command hang. Warn once and keep streaming.
+            # The proxy answers 200 with {"ok":false} when its daemon is gone, so
+            # the body has to be inspected — `curl -f` alone reports that as
+            # success and the agent surface dies silently.
+            #
+            # The daemon has died for two unrelated reasons already (idle reap,
+            # and a killed xcodebuild taking it down), so rather than enumerate
+            # causes, supervise it: whenever it is not healthy, restart it. The
+            # session outlives any single daemon that way. Rate-limited to one
+            # attempt a minute so a permanently broken daemon does not spin.
+            if [ "$AGENT_ENABLED" = "true" ] \
+               && ! curl -fsS -m 10 "http://127.0.0.1:$AGENT_PORT/health" 2>/dev/null \
+                  | grep -q '"ok":true'; then
+              NOW=$(date +%s)
+              if [ $(( NOW - AGENT_LAST_RESTART )) -ge 60 ]; then
+                echo "::warning::agent-device daemon unhealthy; restarting it"
+                AGENT_LAST_RESTART=$NOW
+                pkill -f 'agent-device proxy' 2>/dev/null || true
+                agent-device daemon stop --clean >/dev/null 2>&1 || true
+                nohup agent-device proxy --host 127.0.0.1 --port "$AGENT_PORT" \
+                  --daemon-auth-token "$GATE_TOKEN" >> agent-device-proxy.log 2>&1 &
+                disown
+              fi
+            fi
+            sleep 15
+          done
+          echo "Session window elapsed"
+
+      - name: Mark session ended
+        if: always()
+        run: |
+          gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" \
+            -f state=failure \
+            -f "context=$STATUS_CONTEXT" \
+            -f "description=session ended" || true