Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.
Shell agent-teamsai-agentai-automationanthropicautonomous-agentawsbusiness-operationsclaudeclaude-codeclaude-code-plugindevopsecommerceinbox-zeroklaviyomarketingmcpmorning-briefingpr-automationshopifyterminal
docs(iphonetest): authoritative operator guide for live tunnel drive (#378)
Aurora Capital5cbfc52a67be
diff --git a/docs/operators/iphonetest.md b/docs/operators/iphonetest.mdnew file mode 100644index 00000000..02a46f66--- /dev/null+++ b/docs/operators/iphonetest.md@@ -0,0 +1,636 @@+# `/iphonetest` operator guide — live tunnel drive++Authoritative reference for a Claude session driving a real iPhone on AWS Device Farm+through `/iphonetest --mode tunnel`. Pre-empts every billing-leak, every silent-hang,+and every Appium-extension surprise that has been observed live.++- Upstream slash-command:+ `your-org/my-project` → `.claude/commands/iphonetest.md`+ ([file](https://github.com/your-org/my-project/blob/main/.claude/commands/iphonetest.md))+- Driver script: `my-project/scripts/devicefarm/iphonetest.py` → hands off to+ `tunnel.py` for `--mode tunnel`. This guide documents the **JSON-RPC surface+ of `tunnel.py` as it exists today**, verified against+ [`tunnel.py`](https://github.com/your-org/my-project/blob/main/scripts/devicefarm/tunnel.py).+- Device Farm API surface:+ [`CreateRemoteAccessSession`](https://docs.aws.amazon.com/devicefarm/latest/APIReference/API_CreateRemoteAccessSession.html).+- Appium driver: `appium-xcuitest-driver` —+ [execute-methods reference](https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods/).+ Latest upstream release at time of writing is **v11.7.4 (2026-05-28)**; the+ driver bundled in AWS Device Farm's managed Appium server lags upstream+ (see the "What works vs. what's broken" matrix below).++---++## 1. What `/iphonetest` does++`/iphonetest` is the single entrypoint for driving a real iPhone on AWS Device+Farm from a Claude session. It auto-resolves the latest My-Project staging (or+production) IPA, uploads it to Device Farm, then — depending on `--mode` —+either runs an autonomous Appium + Claude agentic loop (`walkthrough` /+`explore`) or holds open one remote-access session + one Appium WebDriver+connection that an operating agent drives turn-by-turn (`tunnel`). All modes+auto-stop the session on exit so a crashed run cannot leak billing minutes.+Source-of-truth: `my-project/.claude/commands/iphonetest.md`.++## 2. Modes++| `--mode` | Shape | When to use |+|---|---|---|+| `tunnel` **(default since [PR #6172](https://github.com/your-org/my-project/pull/6172))** | Interactive REPL or JSON-RPC over stdio; one session held open across many commands | An operating Claude driving the device turn-by-turn |+| `walkthrough` | Autonomous loop with the built-in My-Project-QA goal (visit every tab, screenshot each) | Smoke a fresh build |+| `explore` | Autonomous loop with operator-supplied `--goal` | Single user-observable outcome, hands-off |++> PR #6172 (merged 2026-05-29 17:48 UTC) flipped the default from `walkthrough`+> to `tunnel`. Prior to that, you had to type `--mode tunnel` explicitly. Today,+> bare `/iphonetest` lands you in interactive tunnel mode.++**`tunnel` is the canonical mode for an operating Claude.** Walkthrough/Explore+are for fire-and-forget runs where no human or agent is steering. The rest of+this guide is about tunnel.++### 2a. Interaction mode on the AWS side++`tunnel.py` always opens a Device Farm remote-access session with+`interactionMode="NO_VIDEO"`. The AWS API exposes three values —+`INTERACTIVE | NO_VIDEO | VIDEO_ONLY` — but only **`NO_VIDEO`** returns a+usable `remoteDriverEndpoint` (HTTPS managed Appium server) suitable for an+Appium WebDriver client. `INTERACTIVE` mode exposes only `interactiveEndpoint`,+which is a WSS video stream meant for a human's browser and is incompatible+with the urllib3-based Appium Python client+(`URLSchemeUnknown('wss')`). The `interactionMode` parameter is marked+deprecated in the AWS API reference — `NO_VIDEO` continues to work and is the+only mode `tunnel.py` will ever request.++Source quote from+[`CreateRemoteAccessSession`](https://docs.aws.amazon.com/devicefarm/latest/APIReference/API_CreateRemoteAccessSession.html):++> *This parameter has been deprecated. The interaction mode of the remote+> access session. … Valid Values: `INTERACTIVE | NO_VIDEO | VIDEO_ONLY`.*++And the verbatim selection logic from `tunnel.py:Tunnel.start`:++```python+# Device Farm exposes two endpoints when interactionMode=NO_VIDEO:+# endpoints.remoteDriverEndpoint -> HTTPS managed Appium server+# endpoints.interactiveEndpoint -> WSS video stream (browser-only)+# The top-level `endpoint` field is the WSS stream and is+# incompatible with the urllib3-based Appium Python client+# (URLSchemeUnknown('wss')).+endpoints = info.get("endpoints") or {}+self.endpoint = (+ endpoints.get("remoteDriverEndpoint")+ or info.get("endpoint")+ or info.get("hostAddress")+ or ""+)+```++## 3. Pre-flight checklist++Run these in order before invoking the command. Abort if any fails.++```bash+# 1. AWS Device Farm project visible (us-west-2 only)+aws devicefarm list-projects --region us-west-2 \+ --query 'projects[].name' --output text+# → expect: My-Project-iOS-E2E++# 2. Doppler secrets present+doppler secrets --project my-project --config dev_local --only-names \+ | grep -E "EAS_ACCESS_TOKEN|EXPO_TOKEN|DEVICEFARM_PROJECT_ARN|BEDROCK_AWS"++# 3. Python deps+pip show boto3 Appium-Python-Client anthropic | grep -E "^Name|^Version"+# missing? → pip install -r scripts/devicefarm/requirements.txt++# 4. No orphan sessions currently billing+python3 scripts/devicefarm/list-sessions.py+# any RUNNING / SCHEDULING listed? → stop them BEFORE you start another:+python3 scripts/devicefarm/stop-session.py --all-active+```++## 4. JSON-RPC command catalogue++`tunnel.py --json` reads one JSON object per stdin line and writes one JSON+response per stdout line. The full handlers dict from `tunnel.py:jsonrpc`:++```python+handlers: dict[str, Any] = {+ "start": lambda m: t.start(+ app_arn=m.get("app_arn"), device_arn=m.get("device_arn")+ ),+ "screenshot": lambda m: t.screenshot(m.get("path")),+ "tap": lambda m: t.tap(float(m["x"]), float(m["y"])),+ "tap_text": lambda m: t.tap_text(m["text"]),+ "swipe": _swipe,+ "type": lambda m: t.type_text(m["text"], submit=bool(m.get("submit", False))),+ "press": lambda m: t.press(m["button"]),+ "wait": lambda m: time.sleep(float(m["seconds"])),+ "status": lambda m: t.status(),+ "stop": _stop,+}+```++`quit` / `exit` are handled separately and trigger the cleanup callback before+acknowledging.++Every command below returns `{"ok": true, ...}` on success or+`{"ok": false, "error": "..."}` on failure. Field reads are by **name** (not+position) so wire order can never swap `tap`'s `x`/`y` or turn `--submit` into+typed text.++### `start`++Reserve a device. Auto-runs at script startup unless `--no-autostart` is+passed. Call explicitly only after a manual `stop`. With `/iphonetest --mode+tunnel`, the IPA ARN is already injected by the orchestrator — you usually do+not call `start` yourself.++```json+{"cmd":"start","app_arn":"arn:aws:devicefarm:us-west-2:...:upload/...","device_arn":"arn:aws:devicefarm:us-west-2::device/..."}+```++Response:++```json+{"ok":true,"session_arn":"arn:aws:devicefarm:...","device":"Apple iPhone 17 Pro","endpoint":"https://...","width":402,"height":874,"artifacts":"artifacts/devicefarm-tunnel/20260529-180000-abcd1234"}+```++`session_arn` and the screen dimensions are what you reference for the rest of+the run.++### `screenshot`++Capture a PNG. Default path is `artifacts/devicefarm-tunnel/<sess>/NNNN.png`+(auto-incremented index). Use an explicit `path` when you want a stable+filename you'll `Read` next turn.++```json+{"cmd":"screenshot","path":"artifacts/iphonetest/run/step-01.png"}+```++Response: `{"ok":true,"path":"...","width":402,"height":874}`.++### `tap`++Tap at point coordinates. Coordinates are in **points** (matches `width` /+`height` from `start` / `screenshot`), not pixels.++```json+{"cmd":"tap","x":201,"y":612}+```++### `tap_text`++Find an element by accessibility label / name / value and tap its center.+Tries exact predicate match first, then `CONTAINS`.++```json+{"cmd":"tap_text","text":"Continue with Apple"}+```++Response includes the matched predicate and rect:++```json+{"ok":true,"matched":"label == \"Continue with Apple\" OR name == \"Continue with Apple\" OR value == \"Continue with Apple\"","rect":{"x":40,"y":596,"width":322,"height":56}}+```++Quoted verbatim from `tunnel.py:Tunnel.tap_text`:++```python+predicates = [+ f'label == "{escaped}" OR name == "{escaped}" OR value == "{escaped}"',+ f'label CONTAINS "{escaped}" OR name CONTAINS "{escaped}" OR value CONTAINS "{escaped}"',+]+```++Fails with `No element matched text '...'` if neither predicate hits. See+gotcha §6.2 for the iOS-system-UI workaround.++### `swipe`++Two forms — direction (convenience) and coordinate (precise).++Direction form (60% screen-distance swipe from center):++```json+{"cmd":"swipe","direction":"up","duration_ms":400}+```++`direction` ∈ `{up,down,left,right}`.++Coordinate form (raw drag):++```json+{"cmd":"swipe","x1":201,"y1":700,"x2":201,"y2":200,"duration_ms":600}+```++Both compile down to `mobile: dragFromToForDuration` on the driver.++### `type`++Send keys to the focused element. `submit: true` appends a newline.++```json+{"cmd":"type","text":"hello Anna","submit":false}+```++Internally this dispatches `mobile: keys` — which the Device Farm-bundled+xcuitest driver **does not expose** on the WDA endpoint. See gotcha §6.1.++### `press`++Hardware-button press. Valid values:+`home | lock | volumeup | volumedown`.++```json+{"cmd":"press","button":"home"}+```++### `wait`++Sleep without sending anything to the device. Use this to let an animation+or network call settle before the next screenshot.++```json+{"cmd":"wait","seconds":2}+```++### `status`++Report session liveness, device name, elapsed seconds, and screen size.++```json+{"cmd":"status"}+```++Response when running: `{"ok":true,"running":true,"session_arn":"...","device":"Apple iPhone 17 Pro","elapsed_sec":143,"width":402,"height":874,"artifacts":"artifacts/devicefarm-tunnel/..."}`.++### `stop`++Stop the Device Farm session **without exiting the tunnel process**. You can+call `start` again after this. If `stop_remote_access_session` raises, the+ARN is **not cleared** and the response is `{"ok": false, "error": "..."}` —+the session may still be billing. Retry with+`python3 scripts/devicefarm/stop-session.py --arn <arn>`.++```json+{"cmd":"stop"}+```++### `quit` / `exit`++Stop the session AND exit the process. Runs cleanup BEFORE acknowledging so+the client sees the actual outcome — a successful response means the device+is no longer billing.++```json+{"cmd":"quit"}+```++Response on clean stop: `{"ok":true,"quit":true}`. On stop failure:+`{"ok":false,"quit":true,"error":"stop_remote_access_session failed; session may still be billing — run scripts/devicefarm/stop-session.py --all-active"}`+(process exits with code 2).++## 5. What works vs. what's broken on Device Farm++Behavior observed live on iPhone 17 Pro / iOS 26.3.1 driving My-Project staging+(2026-05-29). The Appium driver bundled in Device Farm's managed Appium server+lags upstream `appium-xcuitest-driver` v11.7.4+([reference](https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods/)),+which is why some `mobile:` extensions the docs list are not actually+exposed at the WDA endpoint.++| `cmd` | App-rendered My-Project UI | iOS system UI (Springboard / Spotlight) |+|---|---|---|+| `tap` (coords) | ✓ | ✓ |+| `tap_text` | ✓ (every interactive My-Project element ships an accessibility label per `figma-design-system.md`) | ✗ — Springboard / Spotlight system controls (Cancel, search field, App-Library labels) often have no label exposed to WDA's predicate matcher |+| `type` | ✓ for app-rendered text fields with proper accessibility labels (focused-element `set_value` / `send_keys` fallback path inside the driver kicks in) | ✗ — returns `Unhandled endpoint: /wda/element/0/keyboardInput` for the iOS Spotlight / App-Library search field (DF's bundled driver does not expose `mobile: keys`) |+| `swipe` (both forms) | ✓ | ✓ |+| `press` | ✓ | ✓ |+| `screenshot` / `tap` (coords) | ✓ | ✓ — **always usable as the last-resort fallback** |++## 6. Workarounds catalog++Each of these has been hit live; treat the workaround as the primary path+when you recognise the symptom.++### 6.1 `type` returns `Unhandled endpoint: /wda/element/0/keyboardInput`++**Symptom:** `{"cmd":"type","text":"my-project"}` against the iOS Spotlight /+App-Library system search field comes back as+`{"ok":false,"error":"Unhandled endpoint: /wda/element/0/keyboardInput"}`.++**Cause:** Device Farm's bundled `appium-xcuitest-driver` does **not** expose+`mobile: keys` (the extension `tunnel.py:Tunnel.type_text` dispatches). Even+though upstream v11.7.4 documents `mobile: keys`, the managed Appium server+on DF is older / stripped.++**Workaround for app text fields:** the driver's internal fallback to+focused-element `set_value` / `send_keys` works as long as the field has a+proper accessibility label. Focus the field first with `tap_text` (or `tap`+with coords) then re-issue `type`. This is how My-Project staging text inputs+accept input.++**Workaround for iOS system text fields (Spotlight, App Library, Settings+search):** `type` is unusable here. Instead, tap each on-screen keyboard+letter individually by coordinate (read them off the screenshot), or skip+the system search entirely and reach the app via the App-Library route in+§6.3.++### 6.2 `tap_text` returns `No element matched text 'Cancel'`++**Symptom:** `{"cmd":"tap_text","text":"Cancel"}` (or any system-button label+in Springboard / Spotlight / Control Center) fails with+`No element matched text 'Cancel'`.++**Cause:** iOS Springboard and Spotlight UI elements often have no+accessibility label, name, or value exposed via WDA's+`IOS_PREDICATE_STRING` matcher. The two predicate fallbacks inside+`tap_text` both miss.++**Workaround:** screenshot, eyeball the coordinates, and use coordinate+`tap`:++```bash+./tx.sh '{"cmd":"screenshot","path":"01.png"}'+# Read 01.png, locate "Cancel" at e.g. (360, 60)+./tx.sh '{"cmd":"tap","x":360,"y":60}'+```++### 6.3 App is installed but not launched after `start`++**Symptom:** Right after `tunnel.py` reports `{"ok":true,"event":"ready",...}`,+the screenshot shows the iOS home screen — not the My-Project app.++**Cause:** `tunnel.py` installs the IPA on session start (`appArn` is passed+to `create_remote_access_session`), but the Device Farm runtime does **not**+auto-launch it. The bundle is on the device — it's just sitting in App+Library → Recently Added. There is no `cmd` in `tunnel.py` today that+invokes `mobile: launchApp` / `mobile: activateApp` with the staging bundle+id, even though+[both extensions exist upstream](https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods/).++**Workaround:** swipe left to App Library, tap "Recently Added" by coords,+find the My-Project icon.++```bash+./tx.sh '{"cmd":"screenshot","path":"home.png"}'+./tx.sh '{"cmd":"swipe","direction":"left"}' # → today view → app library+./tx.sh '{"cmd":"swipe","direction":"left"}'+./tx.sh '{"cmd":"screenshot","path":"app-library.png"}'+# Read app-library.png, find "Recently Added" stack+./tx.sh '{"cmd":"tap","x":<x>,"y":<y>}'+./tx.sh '{"cmd":"screenshot","path":"recently-added.png"}'+# Tap My-Project icon+./tx.sh '{"cmd":"tap","x":<x>,"y":<y>}'+```++**Followup:** a single-line addition of a `launch_app` / `activate_app` JSON+command in `tunnel.py` (dispatching `mobile: activateApp` with+`bundleId="com.staging.my-project"`) would eliminate this dance. File against+my-project under `scripts/devicefarm` — pure additive change. Until that lands,+the App-Library route is the recipe.++### 6.4 Picker auto-selection (iPhone 17 Pro / iOS 26.3.1)++**Behavior:** the device picker reads the IPA's `metadata.supported_os` ++`metadata.form_factor` via `df.get_upload` and rejects incompatible devices+**before** `create_remote_access_session` is called — so an+`ArgumentException: invalid device or upload` from AWS can never cost you+billing minutes. Highest-OS HIGHLY_AVAILABLE iPhone wins. For the current+My-Project staging IPA, that is iPhone 17 Pro on iOS 26.3.1.++Shipped in+[PR #6171](https://github.com/your-org/my-project/pull/6171)+(merged 2026-05-29 17:34 UTC). No operator action required — just don't pass+`--device-arn` unless you need a specific model.++### 6.5 Session is metered — kill-9 recovery++**Cost:** ~$0.17 per device-minute on metered iPhones. A 50-step walkthrough+runs $1–3. The autonomous loop auto-stops in `finally` and on `SIGTERM`;+`tunnel.py:main._try_stop` is what guarantees that, and a non-zero exit code+(2) is raised if `stop_remote_access_session` failed so CI can alert on+billing leaks.++**A `kill -9` bypasses all of that.** If the tunnel process was force-killed+or the parent shell died, run the recovery one-liner **immediately**:++```bash+doppler run --project my-project --config dev_local -- \+ python3 scripts/devicefarm/stop-session.py --all-active+```++This stops every RUNNING / SCHEDULING session in the project. Confirm with+`python3 scripts/devicefarm/list-sessions.py`.++### 6.6 `NO_VIDEO` is the only Appium-driveable interaction mode++`INTERACTIVE` returns a WSS endpoint that is for humans (browser-rendered+video stream) and is incompatible with the urllib3-based Appium Python+client. `VIDEO_ONLY` is not useful for automation either. `tunnel.py`+hardcodes `interactionMode="NO_VIDEO"` — do not try to override it. The+quoted-verbatim code is in §2a.++### 6.7 FIFO writers must stay open++**Symptom:** the first JSON command works; every subsequent command produces+no output and the screenshot/tap hangs silently.++**Cause:** `printf '{...}\n' > fifo` opens, writes, and **closes** the FIFO.+The reader (`tunnel.py`) sees an EOF and the `for raw in sys.stdin:` loop in+`jsonrpc()` exits. The next write reopens the FIFO but tunnel.py has+already returned and nobody is reading.++**Workaround:** hold one writer open for the lifetime of the run, then+append each command into the same FIFO:++```bash+# 1. Make the FIFO and a holder that never closes it+mkfifo tmp/tunnel/in+( exec 9>tmp/tunnel/in; sleep 86400 ) &+HOLDER_PID=$!+echo "$HOLDER_PID" > tmp/tunnel/holder_pid++# 2. Run tunnel.py reading from the FIFO, mirror output to a log+cat tmp/tunnel/in | python3 scripts/devicefarm/tunnel.py --json \+ --app-arn "$APP_ARN" \+ > tmp/tunnel/out.log 2>&1 &+echo $! > tmp/tunnel/pid++# 3. Send commands by appending to the FIFO from a second writer+printf '{"cmd":"screenshot","path":"01.png"}\n' > tmp/tunnel/in+```++The `tx.sh` helper in §7 wraps this pattern.++### 6.8 `doppler run` wrapper breaks stdin to subprocesses++**Symptom:** `doppler run --project my-project --config dev_local -- bash -c '... python3 tunnel.py --json ...'` either never receives the first JSON command or drops stdin midway.++**Cause:** `doppler run`'s exec wrapper does not reliably forward stdin into a+nested `bash -c "... python3 ..."` invocation, especially when stdin is a+pipe / FIFO.++**Workaround:** materialize the secrets once, source them, and call+`tunnel.py` directly — no doppler wrapper in the hot path:++```bash+doppler secrets download \+ --project my-project --config dev_local \+ --no-file --format env > .env.iphonetest+set -a; source .env.iphonetest; set +a+# Now stdin works normally+python3 scripts/devicefarm/tunnel.py --json --app-arn "$APP_ARN"+```++Delete `.env.iphonetest` when you're done.++## 7. Suggested driving loop for a Claude operator++The pattern below is the one that actually works for a Claude session.+Everything lives under one tmpdir, the FIFO has a permanent holder, and+every command goes through a tiny `tx.sh` that reads the **next** line+written to `out.log` and surfaces it as the JSON response.++### 7.1 Bootstrap++```bash+TMP=$(mktemp -d -t tunnel.XXXXXX)+mkfifo "$TMP/in"+: > "$TMP/out.log"++# Hold the FIFO open so writers never EOF the reader+( exec 9>"$TMP/in"; sleep 86400 ) &+echo $! > "$TMP/holder_pid"++# tx.sh — send one JSON cmd, return the next response line+cat > "$TMP/tx.sh" <<'EOF'+#!/usr/bin/env bash+# Send one JSON cmd, return the next JSON response line from out.log.+# Usage: tx.sh '{"cmd":"screenshot","path":"x.png"}' [timeout_seconds]+set -euo pipefail+TMP="$(dirname "$0")"+CMD="${1:?usage: tx.sh JSON [timeout]}"+TIMEOUT="${2:-180}"+BEFORE=$(wc -l < "$TMP/out.log")+printf '%s\n' "$CMD" > "$TMP/in"+DEADLINE=$(( $(date +%s) + TIMEOUT ))+while [ "$(date +%s)" -lt "$DEADLINE" ]; do+ CUR=$(wc -l < "$TMP/out.log")+ if [ "$CUR" -gt "$BEFORE" ]; then+ sed -n "$((BEFORE+1))p" "$TMP/out.log"+ exit 0+ fi+ sleep 1+done+echo "{\"ok\":false,\"error\":\"tx.sh timeout after ${TIMEOUT}s\"}" >&2+exit 124+EOF+chmod +x "$TMP/tx.sh"++# Materialize secrets once — see gotcha §6.8+doppler secrets download \+ --project my-project --config dev_local \+ --no-file --format env > "$TMP/env"+set -a; source "$TMP/env"; set +a++# Launch the tunnel with /iphonetest (default mode = tunnel since PR #6172)+cat "$TMP/in" | \+ python3 ~/Projects/my-project-workspace/my-project/scripts/devicefarm/iphonetest.py \+ --mode tunnel --json \+ > "$TMP/out.log" 2>&1 &+echo $! > "$TMP/pid"+```++When tunnel.py is ready it writes one JSON line like+`{"ok":true,"event":"ready","session_arn":"...","device":"Apple iPhone 17 Pro","width":402,"height":874,"artifacts":"..."}`.+Read `out.log` until you see `"event":"ready"` before sending the first+command.++### 7.2 Drive++```bash+TX="$TMP/tx.sh"++# 1. Take a baseline screenshot+"$TX" '{"cmd":"screenshot","path":"'"$TMP"'/01.png"}'+# → Read 01.png. iOS home screen — app not auto-launched (gotcha §6.3).++# 2. Swipe to App Library+"$TX" '{"cmd":"swipe","direction":"left"}'+"$TX" '{"cmd":"swipe","direction":"left"}'+"$TX" '{"cmd":"screenshot","path":"'"$TMP"'/02.png"}'++# 3. Tap My-Project icon (coords read from 02.png)+"$TX" '{"cmd":"tap","x":120,"y":240}'+"$TX" '{"cmd":"wait","seconds":2}'+"$TX" '{"cmd":"screenshot","path":"'"$TMP"'/03.png"}'++# 4. Sign in+"$TX" '{"cmd":"tap_text","text":"Continue with Apple"}'+"$TX" '{"cmd":"wait","seconds":3}'+"$TX" '{"cmd":"screenshot","path":"'"$TMP"'/04.png"}'++# 5. Onwards — one screenshot per turn, one decision per turn++# 6. Always end with `quit`+"$TX" '{"cmd":"quit"}'+# → expect {"ok":true,"quit":true}. If "ok":false, run §6.5 recovery.+```++### 7.3 Teardown++```bash+kill "$(cat "$TMP/holder_pid")" 2>/dev/null || true+kill "$(cat "$TMP/pid")" 2>/dev/null || true+rm -f "$TMP/env"+```++After teardown, confirm no orphan sessions:++```bash+python3 ~/Projects/my-project-workspace/my-project/scripts/devicefarm/list-sessions.py+```++## 8. Cost model++| Item | Cost | Notes |+|---|---|---|+| Metered iPhone time | ~$0.17 / device-minute | Charged from RUNNING until `stop_remote_access_session` returns |+| Typical tunnel session | $1–3 per realistic walkthrough | ~6–18 minutes including app launch + sign-in + few flows |+| `--print-only` | $0 | Resolves + uploads the IPA, never reserves a device |+| Idle session during operator thinking | Yes, metered | Plan your next move before sending — but don't paralysis-by-analysis past a couple of minutes |+| Auto-stop guarantee | `finally` + `SIGTERM` + `quit` handler | `tunnel.py:main._try_stop` returns False on stop failure, which raises the process exit code to 2 so CI / supervisors can alert. `kill -9` bypasses this — recover with §6.5 |+| Bedrock tokens | Only in `walkthrough` / `explore` modes | `tunnel` mode has no LLM-per-turn cost; the operating Claude is the brain |++The fundamental rule: **a session that never reaches `stop_remote_access_session` keeps billing.** Always end with `quit`, never `kill -9`, and run §6.5 if anything goes sideways.++## 9. Followups to file++When you hit one of these in the field, file in the my-project repo and link+back to this guide. Do **not** patch them in the same PR that ships this+doc — keep the doc PR pure.++- **`launch_app` / `activate_app` JSON command in `tunnel.py`.** Wraps+ `mobile: activateApp` with `bundleId="com.staging.my-project"` (or the+ resolved production bundle id). Eliminates the App-Library workaround+ in §6.3. One-line handler addition.+- **`mobile: keys` fallback for system text fields.** Either add a+ per-key tap-coords helper for the iOS on-screen keyboard, or document+ that My-Project tests should never depend on driving Spotlight / App-Library+ search.+- **Document the bundled Appium driver version on Device Farm.** A+ `mobile: getEnv` probe at session-start would let `tunnel.py` log the+ WDA build version into `status` so future operators don't re-discover+ the upstream-vs-bundled drift from scratch.++Open these as my-project GitHub issues, link from+`my-project/.claude/commands/iphonetest.md`, and reference back here.++---++Last verified live: 2026-05-29 on iPhone 17 Pro / iOS 26.3.1 against+My-Project staging IPA. When anything in §5 / §6 changes, update this file and+the upstream slash-command in the same PR-pair.