@loadmill/droid-cua 2.43.0 → 2.45.0

package/README.md

@@ -58,10 +58,16 @@ models use your own OpenAI API key.
 - Android: connect a device or select an emulator
 - iOS: choose a simulator on macOS
 
+No app of your own yet? The **Apps** page includes a built-in **Demo Shop**
+Android app. Install it on a connected Android device or emulator, or pick it
+for a cloud Android session, to try the agent right away.
+
 **5. Create or run a test**
 
 Use the desktop app to create a new test, edit an existing one, or run a saved script with live execution logs.
 
+Use the Back and Forward buttons next to the sidebar toggle to revisit pages and selections. Pending editor changes are saved before Back or Forward leaves the page. Automatic batch-test transitions do not add history entries. Report summaries remain visible while switching between saved runs. Navigation history lasts for the current app session; opening a new destination after going back clears forward history.
+
 You can also keep project run history in a results folder and review past runs from desktop app reports.
 
 ---
@@ -69,10 +75,10 @@ You can also keep project run history in a results folder and review past runs f
 <h2 id="platforms">📱 Platforms</h2>
 
 - **Android** - Physical devices and emulators
-- **iOS** - Simulators on macOS
+- **iOS** - Simulators on macOS, and iPhones connected to your Mac by USB
 
 Desktop app support:
-- macOS: Android and iOS simulator workflows
+- macOS: Android, iOS simulator, and iPhone (USB) workflows
 - Windows: Android workflows only
 
 ## Requirements
@@ -90,6 +96,8 @@ Desktop app support:
 - Appium
 - XCUITest driver
 
+**iPhone over USB (macOS only):** see [Testing on a real iPhone](#testing-on-a-real-iphone).
+
 ---
 
 <h2 id="features">✨ Features</h2>
@@ -97,7 +105,7 @@ Desktop app support:
 - **Desktop-first workflow** - Create, run, and manage tests from one app
 - **Setup guidance** - Configure API access and platform prerequisites in the app
 - **Device and simulator connection** - Connect Android targets and iOS simulators
-- **Network certificate preparation** - Manage one active root CA and install it on a connected local simulator or supported emulator from the desktop app's Tools menu
+- **Network certificate preparation** - Manage one active root CA and install it on a connected local simulator or supported emulator, or get manual setup steps for a physical iPhone or Android phone, from the desktop app's Settings → Network capture page
 - **Natural-language test creation** - Describe flows in plain English
 - **Test management** - Create, edit, save, and rerun reusable scripts, including tests organized in nested project folders
 - **Live execution logs** - Watch actions and progress as tests run
@@ -106,15 +114,19 @@ Desktop app support:
 - **Run video export** - Generate and download a polished MP4 replay from a desktop run's screenshots and instruction timeline
 - **Headless support** - Reuse scripts in CLI and automation workflows
 
-**Network certificate preparation:** Use **Tools → Manage Certificates** to see the active CA, upload a single `.pem` containing a CA certificate and its matching unencrypted private key, generate a new Droid CA, or remove the active CA. Droid stores one active pair in `~/.droid-cua/network/`; upload copies the PEM material without changing the source file, and removal does not change device trust. Connect a local iOS Simulator or a rootable Android Emulator, then choose **Tools → Install Network Certificate**. This installs the active CA, generating a Droid CA if none exists. Devices prepared with a previous CA may need installation again. Droid may reapply Android system trust when a prepared emulator reconnects after a cold boot. Restart an already running Android app after installation so it loads the updated trust store. Android certificate setup supports capable rootable images through Android 16; Google Play images without root access and Android 17 are not supported.
+**Network certificate preparation:** Use **Settings → Network capture → Manage certificates** to see the active CA, upload a single `.pem` containing a CA certificate and its matching unencrypted private key, generate a new Droid CA, or remove the active CA. Droid stores one active pair in `~/.droid-cua/network/`; upload copies the PEM material without changing the source file, and removal does not change device trust. Connect a local iOS Simulator or a rootable Android Emulator, then choose **Settings → Network capture → Install on connected device**. This installs the active CA, generating a Droid CA if none exists. Devices prepared with a previous CA may need installation again. Droid may reapply Android system trust when a prepared emulator reconnects after a cold boot. Restart an already running Android app after installation so it loads the updated trust store. With a local iPhone connected by USB, **Settings → Network capture → Install on connected device** does not change the phone; it shows the manual steps instead. **Send to iPhone** opens the macOS share menu with a DER `.cer` copy of the active CA named after its common name (for example `Droid CUA Root fbd877ab.cer`, written to `~/.droid-cua/network/iphone/`); choose AirDrop and your iPhone, install it from **Settings → Profile Downloaded**, then turn on full trust for that common name under **Settings → General → About → Certificate Trust Settings**. Android Emulator certificate setup supports capable rootable images through Android 16; Google Play images without root access and Android 17 are not supported. With a physical Android phone connected over ADB, **Settings → Network capture → Install on connected device** writes a PEM `.crt` copy of the active CA named after its common name (for example `Droid CUA Root fbd877ab.crt`, in `~/.droid-cua/network/android/`), copies it to the phone's `/sdcard/Download/` folder with `adb push`, and shows the manual steps; it changes no phone settings. Install it from **Settings → Security → Encryption & credentials → Install a certificate → CA certificate** (names vary by vendor), then restart the tested app. If the copy fails, Droid shows the local file path so you can copy it to the phone yourself.
 
 **Network capture:** Enable **Network Capture** in desktop Settings or pass `--capture-network` for CLI tests. Local Chrome and Edge capture through Playwright with no certificate or proxy setup, using the same network queries and report cards as mobile. Capture covers the test browser context, including frames and popups, from run start. Previously loaded traffic is not recovered and existing pages are not automatically reloaded. CLI `--url` navigation happens after capture starts. Cloud browser capture, WebSocket messages and HAR export are not supported.
 
 **Mobile setup:** Manually route a prepared local simulator or emulator to `127.0.0.1:8765` (`10.0.2.2:8765` from Android Emulator). Enable **Network Capture** in desktop Settings to keep the proxy forwarding while Droid is open and automatically capture every local mobile test, including each project or scenario case. Existing **Network Proxy** settings do not turn capture on; opt in to the new setting. For CLI tests, pass `--capture-network`; this starts the proxy and writes one JSONL log per test. `--network-proxy` remains a forwarding-only CLI flag. Droid prints or logs each capture path and a best-effort health summary. Desktop artifacts are in the project's results folder; CLI artifacts are beside `--report` output when enabled, or under `logs/`. A missing CA stops mobile capture before test actions. No observed traffic or failed HTTPS decryption is reported separately from test assertions, but capture health does not prove that all traffic was observed. WebSocket messages are unsupported. Manual proxy setup is the V1 workflow. Droid does not change device or Mac proxy settings; turn off manually configured routing when finished. If Droid exits while routing remains enabled, restart Droid or clear the proxy to restore connectivity.
 
+**Physical iPhone capture:** A USB-connected iPhone reaches the proxy over Wi-Fi, so Droid listens on all Mac network interfaces (`0.0.0.0:8765`) instead of `127.0.0.1` while an iPhone is the target: in the CLI when `--avd ios-device:<udid|auto>` is used with `--capture-network` or `--network-proxy`, and in the desktop app while Network Capture is on and a local iPhone is connected (the proxy switches back to `127.0.0.1` on disconnect, but not during a run). Droid prints the setting to use, for example `On the iPhone, set Wi-Fi → Configure Proxy → Manual: server 192.168.1.23, port 8765.` Put the Mac and iPhone on the same Wi-Fi network with device-to-device traffic allowed, install and fully trust the Droid CA manually as described above, and set the iPhone proxy by hand; Droid never changes iPhone settings. Turn the iPhone proxy off after testing. Anyone on the same network can use the proxy while it listens on `0.0.0.0`, so use a trusted network. Apps that pin certificates still connect through the proxy, but their HTTPS is not decrypted.
+
+**Physical Android phone capture:** A phone connected over ADB (any serial other than `emulator-<port>`) is handled the same way as a physical iPhone: Droid listens on `0.0.0.0:8765`, in the CLI once the connected device turns out to be a phone (with `--capture-network` or `--network-proxy`) and in the desktop app while Network Capture is on and the phone is connected. Droid prints the setting to use, for example `On the Android phone, set Wi-Fi → Edit network → Proxy → Manual: hostname 192.168.1.23, port 8765.` Install the CA as a user certificate as described above and set the phone's Wi-Fi proxy by hand; Droid does not root the phone or change its settings, and turn the proxy off after testing. Since Android 7, apps trust user-installed CAs only when their network security config allows it, for example `<certificates src="user"/>` in `network_security_config.xml` or a `<debug-overrides>` block in a debuggable build. Debug and QA builds usually opt in; Play Store builds usually do not, so their HTTPS is not decrypted. Chrome trusts user CAs. Rooted-device system trust is not supported.
+
 Captures stop recording at 100 MiB per run, retaining a partial JSONL with a `CAPTURE_LIMIT` error. Traffic continues forwarding; live network queries report incomplete evidence. Captured bodies are limited to 1 MiB, both on the wire and after decompression. Compressed bodies that expand beyond that limit are omitted with `decoded-body-too-large`; this is incomplete evidence, not a missing response. The separate query evidence limit is 1,000,000 serialized characters. A capture limit or missing traffic is not proof that an application request never occurred.
 
-For troubleshooting, “No traffic observed” points to routing or an app that did not send traffic; it does not prove an expected request was absent. HTTPS connections with no decrypted requests point to certificate trust or interception compatibility. A port-in-use error means another Droid instance or proxy already owns the listener. Stop that listener before starting the CLI. A capture-size or write failure retains only partial evidence. iOS network validation is deferred; ordinary iOS runs without capture do not require proxy or certificate preparation.
+For troubleshooting, “No traffic observed” points to routing or an app that did not send traffic; it does not prove an expected request was absent. HTTPS connections with no decrypted requests point to certificate trust or interception compatibility. A port-in-use error means another Droid instance or proxy already owns the listener. Stop that listener before starting the CLI. A capture-size or write failure retains only partial evidence. Ordinary iOS runs without capture do not require proxy or certificate preparation.
 
 **Network questions and assertions:** With capture enabled, tests can ask Droid to inspect HTTP traffic and compare values across requests in natural language. For example: “Assert that the POST to `/pageview` after opening Home contains the `item_id` returned by `/home`.” The `query_network` tool searches by URL substring, method, status, flow IDs, request timestamps, or a starting step. It considers all matching exchanges in time order and sends only selected headers/bodies to one side call using the selected run model. Large results require a narrower search; they are not silently truncated. Optional observation windows wait the full duration, up to 30 seconds per query. Absence means only “no matching traffic observed during this window”; unavailable capture or insufficient evidence cannot establish absence. Desktop and HTML reports show one collapsed Network query card per call; expand it to see the question and answer. The agent receives structured flow references and capture diagnostics, while model details stay out of the timeline.
 
@@ -207,6 +219,10 @@ droid-cua run tests/auth/login.dcua tests/checkout/purchase.dcua admin/refund.dc
 # Headless iOS simulator run
 droid-cua run tests/login.dcua --platform ios --avd "iPhone 16"
 
+# Check an iPhone connected by USB, then run on it
+droid-cua ios-device check --fix
+droid-cua run tests/login.dcua --avd ios-device:auto
+
 # List running desktop applications and their window IDs (macOS or Windows)
 droid-cua --target desktop --list-desktop-apps
 
@@ -287,7 +303,8 @@ droid-cua \
 ```
 
 Supported CLI options include:
-- `--avd`
+- `--avd` (including `ios-device:<udid>` or `ios-device:auto` for an iPhone connected by USB)
+- `--ios-team`
 - `--platform`
 - `--device-source`
 - `--device-name`
@@ -308,13 +325,14 @@ Supported CLI options include:
 - `--context-optimization-threshold`
 - `--no-context-optimization`
 - `--explain`
+- `--step-watchdog <off|on>`
 - `--base-prompt`
 - `--execution-prompt`
 - `--base-prompt-file`
 - `--execution-prompt-file`
 - `--secrets`
 - `--record`
-- `--network-proxy` (local mobile sessions only; starts idle forwarding at `127.0.0.1:8765`)
+- `--network-proxy` (local mobile sessions only; starts idle forwarding at `127.0.0.1:8765`, or `0.0.0.0:8765` for `--avd ios-device:<udid|auto>` and physical Android phones)
 - `--capture-network` (local mobile and Chrome/Edge test runs; writes a JSONL log for each test, using a proxy only for mobile)
 - `--report`
 - `--report-metadata <path>`
@@ -348,6 +366,7 @@ Config and precedence rules:
 - `--no-context-optimization` disables Context Optimization.
 - Explain Mode is enabled by default and asks the agent for concise explanations of non-obvious decisions, skipped actions, and completion evidence; explanations appear in terminal output and reports.
 - Set `"explainMode": false` in the JSON config to disable it. The `--explain` flag remains available to explicitly enable it for a run.
+- Step Watchdog is experimental and defaults to `off`. Use `--step-watchdog on` to check for failed operations or blocked execution, or `--step-watchdog off` to disable checks. The JSON field is `"stepWatchdogMode": "on"`; the CLI flag overrides it. Desktop users can toggle **Settings → Agent → Verify Step Results** on or off. Successful checks run silently. Failures use an assertion-style **Step Failed** card with the expected instruction, actor explanation, and screenshot. Interactive runs offer **Skip** to continue or **Stop** to fail; headless runs fail automatically. Evaluator errors end execution. Enable `--debug` or desktop **Debug Mode** to inspect `step_watchdog.result` entries; probabilities and evaluator diagnostics remain out of normal output and reports. See [Step Watchdog](docs/step-watchdog.md) for provider requirements, logging, and calibration.
 - `--base-prompt` and `--execution-prompt` let you pass prompt customizations inline on the command line.
 - `--base-prompt-file` and `--execution-prompt-file` override the corresponding prompt customizations from config.
 - If both inline and file-based prompt overrides are provided, the inline prompt flags win.
@@ -375,6 +394,102 @@ HTML report (`--report`):
 droid-cua run tests/login.dcua --avd adb:emulator-5554 --report ./reports
 ```
 
+<h3 id="testing-on-a-real-iphone">Testing on a real iPhone</h3>
+
+The desktop app and the CLI can run tests on your own iPhone connected to your Mac by USB, on the
+apps already installed on it (TestFlight, App Store, or your team's builds).
+droid-cua installs a small helper app (WebDriverAgent) on the iPhone, signed
+with your company's Apple team; nothing is built from source at run time.
+
+Requirements:
+- macOS with an Xcode that supports the iPhone's iOS version, opened once.
+  Its first launch installs the device components and asks for a Mac admin password.
+- The iOS platform installed in that Xcode (**Xcode > Settings > Components**, or
+  `xcodebuild -downloadPlatform iOS`; about 10 GB). Xcode 26 doesn't include it.
+- Your Apple ID signed into Xcode (**Xcode > Settings > Apple Accounts**), as a
+  member of your company's **paid** Apple Developer team, with at least the
+  **Developer** role and **Access to Certificates, Identifiers & Profiles**.
+  Free Apple IDs are not supported.
+- The Appium XCUITest driver, as for Simulators.
+- On the iPhone, once: connect it by USB, unlock it and tap **Trust**; turn on
+  **Developer Mode** (**Settings > Privacy & Security > Developer Mode**, then let it
+  restart and confirm); set **Auto-Lock** to **Never** (**Settings > Display & Brightness**).
+- A test-only iPhone is recommended: droid-cua tests the apps and data already on
+  the phone and never resets it.
+
+Check the iPhone and set it up:
+
+```sh
+droid-cua ios-device check          # report each check and how to fix it
+droid-cua ios-device check --fix    # also set up signing and install the helper app
+```
+
+`ios-device check` prints every check as passed (`✔`), failed (`✖`), or a
+reminder (`!`), with the exact fix for each failure, and exits `0` only when the
+iPhone is ready. Use `--udid <udid>` to choose an iPhone (the first one connected
+by USB is used otherwise). The first `--fix` on a Mac runs a one-time Xcode signing
+build (about a minute); installing the helper app takes a few seconds. A test run
+performs the same checks and fixes automatically before it starts.
+
+**Xcode installed** names what's wrong: Xcode isn't in `/Applications`, the
+Command Line Tools are selected instead of Xcode (fix: `sudo xcode-select -s
+/Applications/Xcode.app`), or the Xcode license isn't accepted (fix: `sudo
+xcodebuild -license accept`). **iOS platform installed** checks that Xcode has the
+iOS platform for its iOS SDK, without which Xcode can't build for an iPhone (fix:
+install it from **Xcode > Settings > Components**, or run `xcodebuild
+-downloadPlatform iOS`, about 10 GB). **Apple team access** reads your teams from Xcode;
+on a fresh Mac, where Xcode hasn't saved them yet, droid-cua fetches them from
+Apple with a short Xcode build (a few seconds, at most once a minute). It then
+says whether no Apple account is signed into Xcode, or you're signed in but none
+of your accounts is in a paid Apple Developer team.
+
+Run tests on the iPhone:
+
+```sh
+droid-cua run tests/login.dcua --avd ios-device:auto
+droid-cua run tests/login.dcua --avd ios-device:00008120-001C18501A81A01E --ios-team ABCDE12345
+```
+
+- `--avd ios-device:<udid>` selects an iPhone; `ios-device:auto` picks the first
+  iPhone connected by USB. The platform is detected as iOS from the token.
+  Running `droid-cua` without `--avd` lists connected iPhones next to Simulators.
+- `--ios-team <TEAMID>` chooses the Apple team that signs the helper app when you
+  belong to several paid teams. `DROID_CUA_IOS_TEAM_ID` works too; the flag wins.
+- `--app` is not used for a local iPhone: tests run against apps already installed
+  on it, so open the app in your test instructions (for example, `Open the Settings app`).
+- After the iPhone restarts, unlock it. On the first run after a restart or a new
+  helper install, the iPhone may ask for your passcode to allow automation; enter
+  it and droid-cua continues. If the iPhone locks during a run, droid-cua pauses
+  until you unlock it.
+- After a major iOS update, droid-cua tells you which Xcode to install and open once.
+
+In the desktop app:
+
+- Run the Setup Wizard (**Help > Run Setup Wizard**) and choose **iPhone (USB)**.
+  The **Connect iPhone** checklist runs the same checks as `ios-device check`.
+  Steps you do on the iPhone or in Xcode (plug in, Trust, Developer Mode, unlock,
+  device components) re-check every few seconds and turn green on their own.
+  **Set up signing** and **Install helper app** run the fix and stream its progress.
+  When the Command Line Tools are selected or the Xcode license isn't accepted,
+  **Xcode installed** offers **Set Xcode Developer Path** or **Accept Xcode License**
+  (both ask for a Mac admin password). When the iOS platform is missing,
+  **iOS platform installed** offers **Download iOS Platform**, which runs
+  `xcodebuild -downloadPlatform iOS` (about 10 GB).
+  Auto-Lock and the dedicated test iPhone are shown as reminders and don't block.
+- If you belong to several paid Apple teams, choose the team in the wizard. The
+  desktop app remembers it and uses it for every iPhone run.
+- Connected iPhones appear in the iOS device picker next to Simulators, with a
+  hint when the iPhone isn't trusted yet or Developer Mode is off. droid tests the
+  apps already installed on the iPhone and never installs any.
+- The connection log and the run view highlight what needs you on the iPhone:
+  *Enter your passcode on the iPhone to allow automation*, *iPhone locked — unlock
+  to continue*, and *Your iPhone is on iOS N. Install Xcode N and open it once.*
+
+Known limits: USB only (no Wi-Fi), one iPhone at a time, attended runs (someone
+needs to unlock the phone and approve prompts), macOS only, and no `.ipa`
+installation. Verified on iOS 26; iOS 17 to 26 are expected to work. iOS betas
+and iOS 27 are not supported yet.
+
 LambdaTest CLI runs:
 - Use `--device-source lambdatest` with `--platform`, `--device-name`, `--os-version`, `--app`, and `--instructions`.
 - Set `LAMBDATEST_USERNAME` and `LAMBDATEST_ACCESS_KEY` in the environment.
@@ -453,7 +568,7 @@ droid-cua \
 
 Headless debug artifacts:
 - `--debug` writes desktop-style structured JSONL artifacts under `logs/`.
-- Each run creates `logs/execution-<runId>-<timestamp>.jsonl`.
+- Each run creates `logs/execution-<runId>-<timestamp>.jsonl`. New run IDs are UUIDs; a batch shares one ID across its tests and aggregate report, and a rerun gets a new ID.
 - Each run also creates a sibling screenshot folder next to that JSONL file.
 - Shared device events are written to `logs/device-events.jsonl`.
 - `--debug` no longer creates the legacy `logs/debug-*.log` file for headless runs.

package/build/index.js

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+import { withExecutionRunId } from "./src/core/execution-context.js";
 const processStartTime = Date.now();
 import minimist from "minimist";
 import dotenv from "dotenv";
@@ -19,7 +21,7 @@ import { resolveExecutionTestData } from "./src/core/test-data.js";
 import { getDefaultSecretsPath, resolveExecutionSecrets } from "./src/core/secrets.js";
 import { assertRuntimeCredentialsForProvider, createRunContext, resolveRuntimeConfigFromEnv, resolveRuntimeCredentialsFromEnv, } from "./src/core/runtime-config.js";
 import { resolveHeadlessExecutionConfig } from "./src/cli/headless-execution-config.js";
-import { artifactKindsForPool, resolveHeadlessTarget, scopeArtifactKindsToPool, shouldWaitForLoadmillCloudCompletion, } from "./src/cli/headless-target.js";
+import { artifactKindsForPool, resolveHeadlessTarget, resolveIosTeamId, scopeArtifactKindsToPool, shouldWaitForLoadmillCloudCompletion, } from "./src/cli/headless-target.js";
 import { createHeadlessDebugArtifacts } from "./src/cli/headless-debug.js";
 import { loadHeadlessInstructions } from "./src/cli/headless-instructions.js";
 import { clearLoadmillReportMetadata } from "./src/cli/loadmill-report-metadata.js";
@@ -38,6 +40,7 @@ import { droidReportUploadManager } from "./src/integrations/loadmill/report-upl
 import { getCloudProviderAdapter } from "./src/device/cloud/registry.js";
 import { setCloudProgressListener } from "./src/device/cloud/progress.js";
 import { runSkillCommand } from "./src/cli/skill-command.js";
+import { runIosDeviceCommand } from "./src/cli/ios-device-command.js";
 import { formatLoadmillCloudNotEntitledMessage, isLoadmillCloudNotEntitledError, isLoadmillCloudUsageLimitError, } from "./src/device/cloud/loadmill-cloud/errors.js";
 import { fetchAndDownloadArtifacts, loadmillCloudAdapter } from "./src/device/cloud/loadmill-cloud/adapter.js";
 import { resolveRunPool } from "./src/device/cloud/loadmill-cloud/run-pool.js";
@@ -46,10 +49,26 @@ import { formatDuration } from "./src/core/report/run-log-model.js";
 import { createBrowserSessionTeardown, withLoadmillCloudSession } from "./src/cli/loadmill-cloud-session.js";
 import { createDesktopController, listDesktopApplications } from "./src/desktop/computer-use.js";
 import { createRunNetworkCapture } from "./src/network/run-network-capture.js";
+import { cliNetworkCaptureDeviceKind, cliNetworkProxyTarget } from "./src/cli/network-capture-device.js";
 import { loadCertificateAuthority } from "./src/network/certificate-authority.js";
 import { ensureCliAndroidCertificate, inspectNetworkDevice } from "./src/network/certificate-install.js";
 dotenv.config();
 let networkCapture = null;
+let cliNetworkProxyHost = null;
+async function startCliNetworkProxy(deviceName) {
+    const { host, instruction } = cliNetworkProxyTarget(deviceName);
+    if (host === cliNetworkProxyHost)
+        return;
+    try {
+        await networkCapture.startProxy({ host });
+    }
+    catch (error) {
+        throw new Error(`Droid network proxy could not start: ${error.message}`, { cause: error });
+    }
+    cliNetworkProxyHost = host;
+    if (instruction)
+        console.log(instruction);
+}
 process.once("SIGTERM", async () => {
     process.exitCode = 143;
     await networkCapture?.shutdown().catch(() => { });
@@ -78,12 +97,23 @@ if (args._[0] === "skill") {
         process.exit(1);
     }
 }
+if (args._[0] === "ios-device") {
+    try {
+        process.exit(await runIosDeviceCommand({ args }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`\niOS device command failed: ${message}`);
+        process.exit(1);
+    }
+}
 const reportMetadataPath = typeof args["report-metadata"] === "string"
     && args["report-metadata"].trim().length > 0
     ? args["report-metadata"].trim()
     : null;
 await clearLoadmillReportMetadata(reportMetadataPath);
 const targetConfig = resolveHeadlessTarget(args);
+const iosTeamId = resolveIosTeamId(args, targetConfig);
 let avdName = targetConfig.avdName;
 let platform = targetConfig.platform || null; // 'ios' or 'android'
 const recordScreenshots = args["record"] || false;
@@ -413,14 +443,8 @@ async function main() {
             process.exit(130);
         });
     }
-    if (networkCapture && !isBrowserTarget) {
-        try {
-            await networkCapture.startProxy();
-        }
-        catch (error) {
-            throw new Error(`Droid network proxy could not start: ${error.message}`, { cause: error });
-        }
-    }
+    if (networkCapture && !isBrowserTarget)
+        await startCliNetworkProxy(avdName);
     let preloadedHeadlessConfig = null;
     let preloadedHeadlessTarget = null;
     let headlessInstructionRuns = [];
@@ -463,6 +487,8 @@ async function main() {
         const selection = await selectDevice();
         platform = selection.platform;
         avdName = selection.deviceName;
+        if (networkCapture)
+            await startCliNetworkProxy(avdName);
     }
     let targetId;
     let deviceInfo;
@@ -801,18 +827,18 @@ async function main() {
         }
     }
     else {
-        targetId = await connectToDevice(avdName, platform);
+        targetId = await connectToDevice(avdName, platform, { teamId: iosTeamId });
+        const deviceKind = networkCapture ? cliNetworkCaptureDeviceKind(getConnectedDevicePlatform(), targetId) : null;
+        if (deviceKind === "android-device")
+            await startCliNetworkProxy(`adb:${targetId}`);
         if (captureNetwork) {
-            const connectedPlatform = getConnectedDevicePlatform();
-            if (connectedPlatform === "android") {
-                if (!/^emulator-\d+$/.test(targetId))
-                    throw new Error("--capture-network supports Android Emulators, not physical Android devices.");
+            if (deviceKind === "android-emulator") {
                 const ca = await loadCertificateAuthority();
                 const trust = await ensureCliAndroidCertificate(targetId, ca);
                 if (trust.changed)
                     console.log(`Reapplied Droid's network certificate on ${targetId}.`);
             }
-            else {
+            else if (deviceKind === "ios-simulator") {
                 await inspectNetworkDevice({ platform: "ios", deviceId: targetId });
             }
         }
@@ -826,6 +852,7 @@ async function main() {
     session.setSystemPrompt(initialSystemText);
     // If tests were selected, run in headless mode.
     if (isHeadlessInstructionsRun) {
+        const runId = randomUUID();
         let exitCode = null;
         let succeeded = false;
         try {
@@ -836,6 +863,7 @@ async function main() {
                 llmProviderMode: headlessConfig.llmProviderMode,
                 cuaModel: headlessConfig.cuaModel,
                 explainMode: headlessConfig.explainMode,
+                stepWatchdogMode: headlessConfig.stepWatchdogMode,
                 promptCustomizations: headlessConfig.promptCustomizations,
                 contextOptimizationEnabled: headlessConfig.contextOptimizationEnabled,
                 contextOptimizationThreshold: headlessConfig.contextOptimizationThreshold,
@@ -851,7 +879,7 @@ async function main() {
             console.log(`Using CUA model: ${runtimeContext.config.cuaModel}`);
             if (headlessConfig.scenarioPrompt) {
                 const candidateRuns = await loadScenarioCandidateRuns(headlessInstructionRuns);
-                const scenarioCases = await planScenarioRuns({
+                const scenarioCases = await withExecutionRunId(runId, () => planScenarioRuns({
                     client: runtimeContext.openAiClient,
                     runtimeConfig: runtimeContext.config,
                     scenarioPrompt: headlessConfig.scenarioPrompt,
@@ -861,7 +889,7 @@ async function main() {
                     })),
                     appContextText,
                     testDataText: preloadedTestData?.text || "",
-                });
+                }));
                 printScenarioCasePreview(scenarioCases);
                 headlessInstructionRuns = buildScenarioRuns({
                     candidateRuns,
@@ -870,6 +898,7 @@ async function main() {
                 preloadedHeadlessTarget = buildScenarioInstructionTarget(preloadedHeadlessTarget, headlessConfig.scenarioPrompt);
             }
             const result = await runHeadlessInstructionRuns({
+                runId,
                 runs: headlessInstructionRuns,
                 instructionsTarget: preloadedHeadlessTarget,
                 session,

package/build/src/cli/device-selector.js

@@ -5,6 +5,7 @@ import React, { useState } from 'react';
 import { render, Box, Text, useInput, useApp } from 'ink';
 import { exec } from "child_process";
 import { promisify } from "util";
+import { getConnectedIphones } from "./ios-device-list.js";
 const execAsync = promisify(exec);
 /**
  * Interactive selection component with arrow key navigation
@@ -171,16 +172,18 @@ async function getIOSDevices() {
  */
 export async function selectDevice() {
     // Check what's available
-    const [androidDevices, iosDevices] = await Promise.all([
+    const [androidDevices, iphones, simulators] = await Promise.all([
         getAndroidDevices(),
+        getConnectedIphones(),
         getIOSDevices(),
     ]);
+    const iosDevices = [...iphones, ...simulators];
     const hasAndroid = androidDevices.length > 0;
     const hasIOS = iosDevices.length > 0;
     if (!hasAndroid && !hasIOS) {
         console.error("\nNo devices found!");
         console.error("  Android: Connect a device or create an AVD, then run droid-cua again");
-        console.error("  iOS: Xcode Simulator must be available");
+        console.error("  iOS: Connect an iPhone by USB or make an Xcode Simulator available");
         process.exit(1);
     }
     // Build platform options
@@ -193,9 +196,13 @@ export async function selectDevice() {
         });
     }
     if (hasIOS) {
-        const runningCount = iosDevices.filter((d) => d.running).length;
+        const runningCount = simulators.filter((d) => d.running).length;
+        const counts = [
+            iphones.length > 0 ? `${iphones.length} iPhone(s)` : null,
+            simulators.length > 0 ? `${simulators.length} simulator(s)` : null,
+        ].filter(Boolean).join(", ");
         platformOptions.push({
-            label: `iOS${runningCount > 0 ? ` (${runningCount} running)` : ""} - ${iosDevices.length} simulator(s)`,
+            label: `iOS${runningCount > 0 ? ` (${runningCount} running)` : ""} - ${counts}`,
             value: "ios",
         });
     }
@@ -211,11 +218,11 @@ export async function selectDevice() {
     }
     // Select device
     const deviceList = platform === "ios" ? iosDevices : androidDevices;
-    const deviceType = platform === "ios" ? "Simulator" : "Android Target";
+    const deviceType = platform === "ios" ? (iphones.length > 0 ? "iOS Device" : "Simulator") : "Android Target";
     let deviceName;
     if (deviceList.length === 1) {
         deviceName = deviceList[0].value;
-        console.log(`Using ${deviceName} (only available ${deviceType.toLowerCase()})\n`);
+        console.log(`Using ${deviceList[0].label} (only available ${deviceType.toLowerCase()})\n`);
     }
     else {
         const selected = await renderSelection(`Select ${deviceType}`, deviceList);

package/build/src/cli/headless-execution-config.js

@@ -1,4 +1,5 @@
 import path from "path";
+import { parseStepWatchdogMode } from "../core/step-watchdog.js";
 import { readFile } from "fs/promises";
 import { DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD, MAX_CONTEXT_OPTIMIZATION_THRESHOLD, MIN_CONTEXT_OPTIMIZATION_THRESHOLD, } from "../core/context-optimization.js";
 import { AIM_ASSIST_MODES, DEFAULT_AIM_ASSIST_MODE } from "../core/aim-assist.js";
@@ -131,6 +132,7 @@ async function loadConfigFromFile(configPath) {
         cuaModel: undefined,
         aimAssistMode: undefined,
         explainMode: undefined,
+        stepWatchdogMode: undefined,
         promptCustomizations: createEmptyPromptCustomizations(),
         appContextEnabled: undefined,
         appContextPath: undefined,
@@ -152,6 +154,9 @@ async function loadConfigFromFile(configPath) {
         }
         normalized.explainMode = rawConfig.explainMode;
     }
+    if ("stepWatchdogMode" in rawConfig) {
+        normalized.stepWatchdogMode = parseStepWatchdogMode(rawConfig.stepWatchdogMode);
+    }
     if ("promptCustomizations" in rawConfig) {
         normalized.promptCustomizations = normalizePromptCustomizations(rawConfig.promptCustomizations, "config.promptCustomizations");
     }
@@ -226,6 +231,7 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         cuaModel: fileConfig?.cuaModel || readEnvDefaultCuaModel(),
         aimAssistMode: fileConfig?.aimAssistMode || DEFAULT_AIM_ASSIST_MODE,
         explainMode: fileConfig?.explainMode ?? true,
+        stepWatchdogMode: fileConfig?.stepWatchdogMode ?? "off",
         promptCustomizations,
         appContextEnabled: fileConfig?.appContextEnabled ?? true,
         appContextPath: fileConfig?.appContextPath || null,
@@ -247,6 +253,9 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     if (args.explain === true) {
         resolved.explainMode = true;
     }
+    if (args["step-watchdog"] !== undefined) {
+        resolved.stepWatchdogMode = parseStepWatchdogMode(args["step-watchdog"]);
+    }
     if (hasContextOptimizationThresholdFlag) {
         resolved.contextOptimizationEnabled = true;
         resolved.contextOptimizationThreshold = parseContextOptimizationThreshold(args["context-optimization-threshold"], "--context-optimization-threshold");

package/build/src/cli/headless-report.js

@@ -16,7 +16,7 @@ export function createCapturingAddOutput(underlying, sink, { cloudSink = null, u
     return (item) => {
         if (item && typeof item === "object") {
             const event = {
-                ts: typeof item.ts === "string" ? item.ts : null,
+                ts: typeof item.ts === "string" && item.ts.trim() ? item.ts : new Date().toISOString(),
                 kind: typeof item.type === "string" ? item.type : "info",
                 text: typeof item.text === "string" ? item.text : "",
                 eventType: item.eventType,
@@ -45,26 +45,52 @@ export function createCapturingAddOutput(underlying, sink, { cloudSink = null, u
 // boolean/error/event signals. Exactly one of {stopped, failures, errors} is ever set, so
 // the shared precedence (error > fail > stopped > skipped > pass) yields the same verdict
 // the CLI produced before — see R1.
-function deriveCounts(success, error, events) {
+function deriveCounts(success, error, events, failureKind) {
     if (success)
         return { failures: 0, errors: 0, stopped: false };
     if (String(error || "").toLowerCase().includes("stopped by user")) {
         return { failures: 0, errors: 0, stopped: true };
     }
+    if (failureKind === "step_watchdog_error")
+        return { failures: 0, errors: 1, stopped: false };
+    if (failureKind === "step_watchdog")
+        return { failures: 1, errors: 0, stopped: false };
     const failedAssertion = events.some((event) => event.eventType === "assertion_result" && event.payload?.passed === false) ||
         String(error || "").startsWith("Assertion failed:");
     return failedAssertion ? { failures: 1, errors: 0, stopped: false } : { failures: 0, errors: 1, stopped: false };
 }
+function deviceReportEvents(deviceInfo, startedAtIso, testName) {
+    if (!deviceInfo)
+        return [];
+    return [{
+            ts: startedAtIso ?? null,
+            kind: "system",
+            text: `Loading test: ${testName ?? "Test run"}`,
+            eventType: "run_started",
+            payload: {
+                deviceName: deviceInfo.device_name,
+                platform: deviceInfo.platform,
+                deviceSource: deviceInfo.source,
+                osVersion: deviceInfo.os_version,
+            },
+        }];
+}
 // Builds a RunReportModel from captured CLI events plus the run's final stats. This is the
 // CLI-acquisition adapter: it knows how to capture live events + run stats, then delegates
 // ALL model assembly to the shared run-report-model.js (same code path as the XML/Desktop
 // parser). A `run_finished` event is synthesized when the captured output stream omits one.
-export function buildCliRunReportModel({ suiteName, testName, startedAtIso, durationMs, success, error, instructionsTotal, stats = {}, events, }) {
+export function buildCliRunReportModel({ suiteName, testName, startedAtIso, durationMs, success, error, failureKind = undefined, stepWatchdogMode = undefined, stepWatchdogUsage = undefined, instructionsTotal, stats = {}, events, deviceInfo = undefined, }) {
     const warnings = [];
     const normalizedEvents = normalizeEvents(events, { fallbackTs: startedAtIso ?? null, warnings });
+    const terminalCheck = normalizedEvents.findLast((event) => event.eventType === "step_watchdog_result" && event.payload?.mode === "on");
+    failureKind ??= terminalCheck?.payload?.outcome === "failure" ? "step_watchdog"
+        : terminalCheck?.payload?.outcome === "error" ? "step_watchdog_error" : undefined;
     const summaryPayload = buildRunFinishedPayload({
         success,
         error,
+        failureKind,
+        stepWatchdogMode,
+        stepWatchdogUsage,
         durationMs,
         instructionsTotal,
         instructionsCompleted: stats.instructionsCompleted,
@@ -74,15 +100,18 @@ export function buildCliRunReportModel({ suiteName, testName, startedAtIso, dura
         retries: stats.retryCount,
     });
     const hasRunFinished = normalizedEvents.some((event) => event.eventType === "run_finished");
-    // The synthetic run_finished is already in canonical shape; append it as-is (ts stays
-    // null, matching the historical CLI output) only when the producer did not emit one.
+    // Use execution time, not report generation/upload time, for the final step boundary.
+    const startedAtMs = Date.parse(startedAtIso);
+    const finishedAt = Number.isFinite(startedAtMs) && Number.isFinite(durationMs) && durationMs >= 0
+        ? new Date(startedAtMs + durationMs).toISOString()
+        : null;
     const allEvents = hasRunFinished
         ? normalizedEvents
         : [
             ...normalizedEvents,
-            { ts: null, kind: "system", text: "Execution finished", eventType: "run_finished", payload: summaryPayload },
+            { ts: finishedAt, kind: "system", text: "Execution finished", eventType: "run_finished", payload: summaryPayload },
         ];
-    const { failures, errors, stopped } = deriveCounts(success, error, allEvents);
+    const { failures, errors, stopped } = deriveCounts(success, error, allEvents, failureKind);
     const status = deriveRunStatus({ tests: 1, failures, errors, stopped });
     const successRate = computeSuccessRate({ tests: 1, failures, errors, status });
     return assembleRunReportModel({
@@ -96,7 +125,7 @@ export function buildCliRunReportModel({ suiteName, testName, startedAtIso, dura
         failureOrError: success
             ? undefined
             : makeFailureOrError({ kind: status === "error" ? "error" : "failure", message: error ?? undefined }),
-        events: allEvents,
+        events: [...deviceReportEvents(deviceInfo, startedAtIso, testName), ...allEvents],
         warnings,
     });
 }
@@ -127,7 +156,7 @@ export function createCliRunReport(modelInput) {
         }),
     };
 }
-export function createCliAggregateRunReport({ suiteName, testName, startedAtIso, durationMs, childModels, }) {
+export function createCliAggregateRunReport({ suiteName, testName, startedAtIso, durationMs, childModels, deviceInfo = undefined, }) {
     const childTests = childModels.map((model) => ({
         testName: model.testName ?? "Test",
         durationSeconds: model.durationSeconds,
@@ -162,7 +191,7 @@ export function createCliAggregateRunReport({ suiteName, testName, startedAtIso,
             skipped,
             status,
         }),
-        events: [],
+        events: deviceReportEvents(deviceInfo, startedAtIso, testName),
         childTests,
         warnings: [],
     });
@@ -183,7 +212,7 @@ export function renderCliCloudReport(model, savedRunId) {
     for (const child of cloudModel.childTests ?? []) {
         replaceScreenshots(child.events);
     }
-    return renderHtmlReport(cloudModel, { includeScripts: false });
+    return renderHtmlReport(cloudModel, { includeScripts: false, showRunDetails: false });
 }
 export async function writeCliRunReportArtifact(artifact, { reportPath, cwd = process.cwd(), isBatch = false } = {}) {
     const outputPath = resolveReportOutputPath({