@autifyhq/aximo-cli 0.6.0 → 0.7.0

package/README.md

@@ -64,47 +64,47 @@ Credentials and device registrations are **per-environment** — to switch betwe
 
 Run `aximo <command> --help` for detailed usage. `aximo schema [command.path]` returns machine-readable argument introspection (e.g. `aximo schema session.create`).
 
-| Command                      | Description                                             |
-| ---------------------------- | ------------------------------------------------------- |
-| `aximo configure`            | Save credentials to `$AXIMO_HOME/config.json`           |
-| `aximo health check`         | Check API reachability                                  |
-| `aximo project list`         | List organization projects                              |
-| `aximo session create`       | Create and queue a test session                         |
-| `aximo session get`          | Get session status                                      |
-| `aximo session save-as-case` | Save a finished session as a reusable test case         |
-| `aximo case create`          | Create a test case                                      |
-| `aximo case delete`          | Delete a test case                                      |
-| `aximo plan create`          | Create a test plan                                      |
-| `aximo plan add-case`        | Add a case to a plan                                    |
-| `aximo plan remove-case`     | Remove a case from a plan                               |
-| `aximo trigger case run`     | Trigger a dashboard-created test case                   |
-| `aximo trigger case get`     | Get triggered case status                               |
-| `aximo trigger plan run`     | Trigger a test plan                                     |
-| `aximo trigger plan get`     | Get plan run status                                     |
-| `aximo upload create`        | Create an upload slot for an APK/IPA                    |
-| `aximo upload list`          | List previously uploaded apps                           |
-| `aximo upload get`           | Poll upload processing status                           |
-| `aximo upload put`           | Upload binary file to the slot                          |
-| `aximo upload submit`        | Finalize upload and trigger processing                  |
-| `aximo device list`          | List mobile devices from Device Farm                    |
-| `aximo device setup`         | First-time BYOD onboarding (API + Python + register)    |
-| `aximo device register`      | Register this machine as a BYOD device                  |
-| `aximo device connect`       | Start the BYOD agent and connect to the relay           |
-| `aximo device status`        | List your organization's BYOD devices                   |
-| `aximo device ping`          | Check your BYOD device's server-side status             |
-| `aximo device doctor`        | Diagnose BYOD setup (env, Python, relay, status)        |
-| `aximo device logs`          | Show the BYOD agent log                                 |
-| `aximo device unregister`    | Remove a BYOD device server-side + clear local creds    |
-| `aximo device reset`         | Remove BYOD local state (Python, deps, credentials)     |
-| `aximo mobile list`          | List physically-connected phones (Android adb, iOS idb) |
-| `aximo mobile setup`         | Install the Appium drivers used to drive phones         |
-| `aximo mobile doctor`        | Diagnose prerequisites (adb/idb, SDK/Xcode, driver)     |
-| `aximo mobile register`      | Register a connected Android phone or iPhone            |
-| `aximo mobile install`       | Install an app (.apk via adb, .ipa via idb)             |
-| `aximo mobile connect`       | Start managed Appium + open the tunnel for the phone    |
-| `aximo mobile unregister`    | Remove a local mobile device server-side + local creds  |
-| `aximo schema`               | Show CLI surface as JSON                                |
-| `aximo mcp`                  | Run a stdio MCP server for agents (see below)           |
+| Command                      | Description                                                    |
+| ---------------------------- | -------------------------------------------------------------- |
+| `aximo configure`            | Save credentials to `$AXIMO_HOME/config.json`                  |
+| `aximo health check`         | Check API reachability                                         |
+| `aximo project list`         | List organization projects                                     |
+| `aximo session create`       | Create and queue a test session                                |
+| `aximo session get`          | Get session status                                             |
+| `aximo session save-as-case` | Save a finished session as a reusable test case                |
+| `aximo case create`          | Create a test case                                             |
+| `aximo case delete`          | Delete a test case                                             |
+| `aximo plan create`          | Create a test plan                                             |
+| `aximo plan add-case`        | Add a case to a plan                                           |
+| `aximo plan remove-case`     | Remove a case from a plan                                      |
+| `aximo trigger case run`     | Trigger a dashboard-created test case                          |
+| `aximo trigger case get`     | Get triggered case status                                      |
+| `aximo trigger plan run`     | Trigger a test plan                                            |
+| `aximo trigger plan get`     | Get plan run status                                            |
+| `aximo upload create`        | Create an upload slot for an APK/IPA                           |
+| `aximo upload list`          | List previously uploaded apps                                  |
+| `aximo upload get`           | Poll upload processing status                                  |
+| `aximo upload put`           | Upload binary file to the slot                                 |
+| `aximo upload submit`        | Finalize upload and trigger processing                         |
+| `aximo device list`          | List mobile devices from Device Farm                           |
+| `aximo device setup`         | First-time BYOD onboarding (API + Python + register)           |
+| `aximo device register`      | Register this machine as a BYOD device                         |
+| `aximo device connect`       | Start the BYOD agent and connect to the relay                  |
+| `aximo device status`        | List your organization's BYOD devices                          |
+| `aximo device ping`          | Check your BYOD device's server-side status                    |
+| `aximo device doctor`        | Diagnose BYOD setup (env, Python, relay, status)               |
+| `aximo device logs`          | Show the BYOD agent log                                        |
+| `aximo device unregister`    | Remove a BYOD device server-side + clear local creds           |
+| `aximo device reset`         | Remove BYOD local state (Python, deps, credentials)            |
+| `aximo mobile list`          | List physically-connected phones (Android adb, iOS devicectl)  |
+| `aximo mobile setup`         | Install the Appium drivers used to drive phones                |
+| `aximo mobile doctor`        | Diagnose prerequisites (adb/Xcode/devicectl, signing, driver)  |
+| `aximo mobile register`      | Register a connected Android phone or iPhone                   |
+| `aximo mobile install`       | Install an app (.apk via adb, .ipa auto-re-signed + devicectl) |
+| `aximo mobile connect`       | Start managed Appium + open the tunnel for the phone           |
+| `aximo mobile unregister`    | Remove a local mobile device server-side + local creds         |
+| `aximo schema`               | Show CLI surface as JSON                                       |
+| `aximo mcp`                  | Run a stdio MCP server for agents (see below)                  |
 
 Mutating commands support `--json '<raw body>'` for direct OpenAPI payloads and `--dry-run` to preview requests without executing.
 
@@ -405,7 +405,7 @@ Default `$AXIMO_HOME` is `~/.aximo` on macOS/Linux, `%USERPROFILE%\.aximo` on Wi
 
 The `mobile` commands let you register a **physically-connected Android phone or iPhone** as an Aximo device and drive it locally, over the same gateway tunnel as desktop BYOD. Aximo's agent controls the phone through a CLI-managed [Appium](https://appium.io) server — UiAutomator2 for Android, XCUITest for iOS — useful for running mobile tests against your own handset instead of a Device Farm device.
 
-> **iOS is macOS-only and needs Xcode + an Apple Developer account.** Driving a physical iPhone goes through Appium's XCUITest driver, which builds and code-signs a WebDriverAgent (WDA) runner onto the device. That requires macOS, Xcode, an Apple Developer **Team ID**, and a WDA bundle id backed by a valid provisioning profile — set via the `AXIMO_IOS_*` env vars below. Android has no such requirement, so iOS setup is heavier; everything after setup (`register` → `connect` → run) works the same on both platforms.
+> **iOS is macOS-only and needs Xcode + an Apple ID.** Driving a physical iPhone requires a development-signed WebDriverAgent (WDA) runner on the device — an Apple platform rule, not an Aximo one. The CLI is **zero-config about it**: it discovers your signing identity and Team ID from the keychain, finds or mints provisioning profiles via Xcode automatic signing, and (on iOS 17+) preinstalls a prebuilt WDA with no Xcode build. A free/personal Apple ID works. Android has no signing requirement, so iOS setup is heavier; everything after setup (`register` → `connect` → run) works the same on both platforms.
 
 Terminology note: **`aximo mobile list`** shows phones plugged into _this_ machine; **`aximo device list`** (under [Device / BYOD](#device-byod--bring-your-own-device)) returns mobile devices from AWS Device Farm. Don't confuse the two.
 
@@ -418,7 +418,7 @@ Terminology note: **`aximo mobile list`** shows phones plugged into _this_ machi
   - **iOS** — **Developer Mode** enabled (Settings → Privacy & Security) and the computer trusted.
 - **On the machine that runs `aximo mobile connect`**:
   - **Android** — `adb` and the Android SDK, with `ANDROID_HOME` set — see [Set up your computer (Android)](#set-up-your-computer-android).
-  - **iOS** — macOS with **Xcode** + command line tools, **`idb`**, and the `AXIMO_IOS_*` signing env vars — see [Set up your computer (iOS)](#set-up-your-computer-ios).
+  - **iOS** — macOS with **Xcode** and an Apple ID signed into it — see [Set up your computer (iOS)](#set-up-your-computer-ios).
 
 > The Appium server is bundled with the CLI; `aximo mobile setup` installs the UiAutomator2 (Android) and/or XCUITest (iOS) driver — you don't install or manage Appium yourself.
 
@@ -460,30 +460,43 @@ source ~/.bashrc
 
 ### Set up your computer (iOS)
 
-iOS local devices are **macOS-only** (Appium's XCUITest driver delegates to Xcode). You need Xcode, `idb`, and the signing env vars.
+iOS local devices are **macOS-only** (device control delegates to Xcode's toolchain). Setup is two steps — no env vars:
 
 ```bash
-# 1. Xcode + command line tools (XCUITest builds WebDriverAgent with them):
-xcode-select --install          # or install Xcode from the App Store, then: sudo xcodebuild -license accept
+# 1. Xcode (full app, from the App Store) + accept the license:
+sudo xcodebuild -license accept
 
-# 2. idb — discovers connected iPhones and installs .ipa builds:
-brew tap facebook/fb && brew install idb-companion
-pipx install fb-idb             # or: pip install fb-idb
-
-# 3. Signing config for WebDriverAgent (required for a physical iPhone):
-export AXIMO_IOS_TEAM_ID="ABCDE12345"     # your Apple Developer Team ID (developer.apple.com/account → Membership)
-# Optional overrides (sensible defaults shown):
-export AXIMO_IOS_SIGNING_ID="Apple Development"
-export AXIMO_IOS_WDA_BUNDLE_ID="com.facebook.WebDriverAgentRunner"
-# Optional: reuse a prebuilt WDA to skip per-session rebuilds:
-# export AXIMO_IOS_DERIVED_DATA_PATH="$HOME/Library/Developer/Xcode/DerivedData/WebDriverAgent-xxxx"
+# 2. Sign into Xcode with your Apple ID and create a development certificate:
+#    Xcode → Settings → Accounts → + (your Apple ID)
+#    → Manage Certificates… → + → Apple Development
 ```
 
-`AXIMO_IOS_TEAM_ID` is the load-bearing setting: the XCUITest driver uses it (with the signing id and WDA bundle id) to build and sign WebDriverAgent so it can run on the device. The WDA bundle id must be associated with a valid provisioning profile under that team. Run `aximo mobile doctor --platform ios` to confirm Xcode, `idb`, and the signing config are all present.
+Everything else is discovered automatically at `connect`/`install` time:
+
+- **Signing identity & Team ID** — read from the keychain (`security find-identity`); no `AXIMO_IOS_TEAM_ID` needed. On a machine with several teams, set `AXIMO_IOS_TEAM_ID` (or MobileLink's `XCODE_TEAM_ID`) to pick one.
+- **Provisioning profiles** — scanned from disk and matched against the device; when none fits, the CLI **mints one via Xcode automatic signing** (first run takes a minute or two; requires the Apple ID signed into Xcode).
+- **WebDriverAgent** — on **iOS 17+**, a prebuilt WDA matching the bundled driver is downloaded, re-signed with your identity, and **preinstalled — no Xcode build, no iOS platform download**. Older devices fall back to the classic Xcode build (cached per device under `$AXIMO_HOME/ios-wda/<udid>/`). A WDA bundle id is derived per team (existing `*.WebDriverAgentRunner` profiles are reused); override with `AXIMO_IOS_WDA_BUNDLE_ID`.
+- **App installs** — `.ipa` files that aren't signed for your device are **re-signed automatically** (see `aximo mobile install` below).
+- **Device discovery** — via Xcode's `devicectl`; `idb` is only an optional fallback (`brew install idb-companion && pipx install fb-idb`).
 
-> Already set up Autify's MobileLink? The CLI also reads MobileLink's names as fallbacks — `XCODE_TEAM_ID`, `XCODE_SIGN_ID`, `WDA_BUNDLE_ID` — so an existing host needs no reconfiguration. `AXIMO_IOS_*` takes precedence when both are set.
+Optional overrides / opt-outs:
 
-> First connect to a physical iPhone is slow: Xcode builds and installs WebDriverAgent (a minute or two). If the build fails on signing, open `WebDriverAgent.xcodeproj` in Xcode once, pick your team, and let it auto-manage signing — or set `AXIMO_IOS_DERIVED_DATA_PATH` to a prebuilt WDA.
+```bash
+# export AXIMO_IOS_TEAM_ID="ABCDE12345"   # pick a team on multi-team machines (else auto-detected)
+# export AXIMO_IOS_SIGNING_ID="Apple Development"
+# export AXIMO_IOS_WDA_BUNDLE_ID="com.<you>.WebDriverAgentRunner"  # else derived/reused automatically
+# export AXIMO_IOS_NO_RESIGN=1            # never re-sign the app under test
+# export AXIMO_IOS_NO_PREINSTALLED_WDA=1  # force the classic Xcode build flow for WDA
+# export AXIMO_IOS_DERIVED_DATA_PATH=...  # pin a prebuilt WDA DerivedData (build flow)
+# export AXIMO_IOS_NO_WDA_CACHE=1         # disable the WDA build cache (build flow)
+# export AXIMO_IOS_SKIP_TUNNEL=1          # don't auto-start the RemoteXPC device tunnel (you manage it)
+```
+
+Run `aximo mobile doctor --platform ios` to see what was discovered (identity, team, WDA id) and what's missing; failed commands include a `hint` naming the exact fix.
+
+> **On-device steps you can't skip** (Apple requires them once per phone): enable **Developer Mode** (Settings → Privacy & Security → Developer Mode; the phone restarts), tap **Trust This Computer**, and — after the first install of an app signed by your team — **trust the developer certificate** (Settings → General → VPN & Device Management → your "Apple Development" profile → Trust; the phone needs internet). On **free/personal teams** profiles expire every ~7 days; the CLI re-mints them automatically, but a re-mint **resets the certificate trust**, so expect that trust tap to recur weekly. Free teams are also capped at 10 App IDs per week.
+>
+> On **iOS 17+**, `aximo mobile connect` also starts a small **device tunnel that needs admin rights** — it prompts once for your macOS password / Touch ID (reused on later runs, so at most once per boot). Devices below iOS 17 skip the tunnel entirely. If anything mentions "iOS X is not installed", run `xcodebuild -downloadPlatform iOS` (only the classic build flow needs it).
 
 ### Enable USB debugging on the phone
 
@@ -507,10 +520,10 @@ aximo mobile setup                          # installs the Appium driver(s) for
 aximo mobile doctor                         # checks tooling / drivers / bundled server
 # Limit to one platform if you only test on one:
 aximo mobile setup  --platform ios          # installs only the XCUITest driver
-aximo mobile doctor --platform ios          # checks Xcode / idb / signing config
+aximo mobile doctor --platform ios          # checks Xcode / devicectl / discovered signing
 ```
 
-`setup` installs the Appium driver(s) — UiAutomator2 for Android, XCUITest for iOS — then prints what (if anything) is still missing. `doctor` is the first thing to run when anything's off: for Android it reports `adb` and the Android SDK; for iOS it reports `xcrun`/Xcode, `idb`, and your `AXIMO_IOS_TEAM_ID` signing config — alongside the bundled Appium server and driver — and exits non-zero if a required check fails.
+`setup` installs the Appium driver(s) — UiAutomator2 for Android, XCUITest for iOS — then prints what (if anything) is still missing. `doctor` is the first thing to run when anything's off: for Android it reports `adb` and the Android SDK; for iOS it reports `xcrun`/Xcode, the discovered signing identity/team, and whether the iOS device tunnel is running — alongside the bundled Appium server and driver — and exits non-zero if a required check fails.
 
 ### Registering and connecting
 
@@ -526,7 +539,7 @@ aximo mobile connect                                         # starts managed Ap
 # Ctrl+C to disconnect
 ```
 
-`register` writes credentials to `$AXIMO_HOME/mobile-devices/<deviceId>.json` (mode `0600`). It targets the single connected phone by default — pass `--serial` (Android) or `--udid` (iOS) to pick a specific one when several are attached. `connect` re-checks prerequisites, starts the managed Appium server, and opens the tunnel; it runs until Ctrl+C. If you have more than one registered phone, pass `--device-id` to choose which to connect.
+`register` writes credentials to `$AXIMO_HOME/mobile-devices/<deviceId>.json` (mode `0600`). It targets the single connected phone by default — pass `--serial` (Android) or `--udid` (iOS) to pick a specific one when several are attached. `connect` re-checks prerequisites, then — on iOS 17+ — ensures the device tunnel is running (prompting once for admin the first time), starts the managed Appium server, and opens the gateway tunnel to Aximo; it runs until Ctrl+C. If you have more than one registered phone, pass `--device-id` to choose which to connect.
 
 Once connected, create a **mobile session in Aximo targeting this local device** — the agent routes its actions through the tunnel to the phone over Appium.
 
@@ -536,9 +549,11 @@ Unlike Device Farm, a local phone runs the apps already installed on it. To test
 
 ```bash
 aximo mobile install --app ./app-debug.apk    # Android: adb install -r
-aximo mobile install --app ./MyApp.ipa         # iOS: idb install (the .ipa must be signed for the device)
+aximo mobile install --app ./MyApp.ipa         # iOS: auto-re-signed for the device if needed, installed via devicectl
 ```
 
+On iOS the CLI inspects the `.ipa` first: if its embedded profile already covers the device it installs as-is; otherwise it **re-signs it with your discovered identity** (the same thing AWS Device Farm does to every upload — so the exact `.ipa` you upload there works here). When the bundle id has to be remapped (free teams), launches by the original bundle id are translated automatically during `connect` sessions, and the JSON result reports both ids. App Store downloads are FairPlay-encrypted and can't be re-signed — use a development/ad-hoc build. Opt out with `AXIMO_IOS_NO_RESIGN=1`.
+
 Then create the session with the app's bundle id / package name as `--bundle-id` — the agent launches it on startup before the test begins:
 
 ```bash

package/dist/client.js

@@ -94,7 +94,22 @@ export async function requestToFile(path, destPath, deps = {}) {
     const baseUrl = deps.baseUrl ?? getBaseUrl();
     const fetchImpl = deps.fetchImpl ?? fetch;
     const url = buildUrl(baseUrl, path);
-    const res = await fetchImpl(url, { method: "GET", headers: { "x-api-key": apiKey } });
+    // Redirects (e.g. to a presigned S3 URL) are followed manually WITHOUT the
+    // x-api-key header — fetch only strips authorization/cookie on cross-origin
+    // redirects, so auto-follow would leak the org API key to the storage host.
+    let res = await fetchImpl(url, {
+        method: "GET",
+        headers: { "x-api-key": apiKey },
+        redirect: "manual",
+    });
+    // Only true redirects — other 3xx (e.g. 304 Not Modified) carry no Location
+    // and must fall through to normal handling instead of throwing here.
+    if ([301, 302, 303, 307, 308].includes(res.status)) {
+        const location = res.headers.get("location");
+        if (!location)
+            throw new Error(`Redirect from ${path} is missing a Location header`);
+        res = await fetchImpl(new URL(location, url).toString(), { method: "GET" });
+    }
     if (!res.ok) {
         const retryAfter = res.headers.get("retry-after") ?? undefined;
         throw httpError(res.status, await errorMessage(res), retryAfter);

package/dist/commands/mobile/connect-core.d.ts

@@ -1,5 +1,6 @@
 import type { ErrorEnvelope } from "../../types.js";
 import type { MobileController } from "../../mobile-control/controller.js";
+import { type IosSigningConfig } from "../../mobile-control/ios-signing.js";
 import { type MobileDeviceConfig } from "./paths.js";
 export declare function getTunnelOrigin(): string;
 interface ConfigOk {
@@ -7,6 +8,6 @@ interface ConfigOk {
     config: MobileDeviceConfig;
 }
 export declare function resolveDeviceConfig(deviceId: string | undefined): ConfigOk | ErrorEnvelope;
-export declare function buildController(config: MobileDeviceConfig, endpoint: string): MobileController;
+export declare function buildController(config: MobileDeviceConfig, endpoint: string, iosSigning?: IosSigningConfig, wdaLocalPort?: number | (() => Promise<number>)): MobileController;
 export declare function connectWithConfig(config: MobileDeviceConfig): Promise<void>;
 export {};

package/dist/commands/mobile/connect-core.js

@@ -2,8 +2,13 @@ import { getBaseUrl } from "../../client.js";
 import { formatError } from "../../output.js";
 import { AppiumController } from "../../mobile-control/appium-controller.js";
 import { installUploadedApp } from "../../mobile-control/app-install.js";
-import { startAppiumServer } from "../../mobile-control/appium-server.js";
-import { resolveIosSigning } from "../../mobile-control/ios-signing.js";
+import { pickFreePort, startAppiumServer } from "../../mobile-control/appium-server.js";
+import { withBundleIdTranslation } from "../../mobile-control/bundle-id-map.js";
+import { getIosDeviceInfo, iosMajorVersion } from "../../mobile-control/ios-devicectl.js";
+import { ensureIosTunnel } from "../../mobile-control/ios-tunnel.js";
+import { resolveIosSigning, resolveIosSigningAuto, } from "../../mobile-control/ios-signing.js";
+import { resolveWdaCaching } from "../../mobile-control/ios-wda-cache.js";
+import { resolvePreinstalledWdaStrategy } from "../../mobile-control/ios-wda-preinstall.js";
 import { runControlTunnel } from "../../mobile-control/tunnel.js";
 import { runMobileDoctor } from "./doctor.js";
 import { listMobileDeviceConfigs, readMobileDeviceConfig, } from "./paths.js";
@@ -33,12 +38,14 @@ export function resolveDeviceConfig(deviceId) {
     }
     return { ok: true, config: only };
 }
-export function buildController(config, endpoint) {
+export function buildController(config, endpoint, iosSigning, wdaLocalPort) {
     return new AppiumController({
         endpoint,
         platform: config.platform,
         target: config.target,
-        ...(config.platform === "ios" ? { iosSigning: resolveIosSigning() } : {}),
+        ...(config.platform === "ios"
+            ? { iosSigning: iosSigning ?? resolveIosSigning(), ...(wdaLocalPort ? { wdaLocalPort } : {}) }
+            : {}),
     });
 }
 // A blocking check is any hard failure, plus a missing automation driver
@@ -61,23 +68,114 @@ async function assertPrerequisites(platform) {
     throw new Error(`Missing ${platform} prerequisites:\n${lines.join("\n")}\n` +
         `Run \`${setup}\` and/or fix the above, then re-run. (\`${doctor}\` for details.)`);
 }
+/**
+ * Preflight the physical device state via devicectl and fail with the exact
+ * on-device fix when an onboarding toggle is missing. Returns the device's iOS
+ * major version (null when devicectl can't see the device).
+ */
+async function preflightIosDevice(udid) {
+    const info = await getIosDeviceInfo(udid);
+    if (!info)
+        return null;
+    if (info.developerModeEnabled === false) {
+        throw new Error("Developer Mode is disabled on the iPhone. Enable it on the device: Settings → " +
+            "Privacy & Security → Developer Mode → On (the phone restarts), then re-run.");
+    }
+    if (info.paired === false) {
+        throw new Error("The iPhone is not paired with this Mac. Unlock the phone, reconnect the USB cable, " +
+            "and tap 'Trust This Computer'.");
+    }
+    return iosMajorVersion(info.osVersion);
+}
 export async function connectWithConfig(config) {
     await assertPrerequisites(config.platform);
+    let iosMajor = null;
+    if (config.platform === "ios") {
+        iosMajor = await preflightIosDevice(config.target);
+        // Physical iPhones on iOS 17+ need the RemoteXPC tunnel before XCUITest can
+        // reach WebDriverAgent; start it (prompting for admin) unless one is running.
+        // Older devices use the classic lockdown path — no tunnel, no admin prompt.
+        if (iosMajor !== null && iosMajor < 17) {
+            console.error(`iOS ${iosMajor} device — skipping the RemoteXPC tunnel (not needed).`);
+        }
+        else {
+            const tunnel = await ensureIosTunnel();
+            if (tunnel.reused)
+                console.error("Reusing the running iOS device tunnel.");
+        }
+    }
     const useDrivers = config.platform === "ios" ? ["xcuitest"] : ["uiautomator2"];
     const server = await startAppiumServer({ useDrivers });
-    const controller = buildController(config, server.endpoint);
+    // WDA strategy ladder: (1) preinstalled prebuilt runner — no xcodebuild at all
+    // (iOS 17+, needs a discovered identity; profiles are minted on demand);
+    // (2) cached xcodebuild output (usePrebuiltWDA) when still valid; (3) full
+    // driver-managed xcodebuild. Everything is discovered from the keychain and
+    // installed profiles; env vars only override.
+    let iosSigning;
+    let wdaLocalPort;
+    if (config.platform === "ios") {
+        const signing = await resolveIosSigningAuto({ udid: config.target });
+        if (signing.teamId) {
+            console.error(`Signing as team ${signing.teamId} (WDA id ${signing.wdaBundleId}).`);
+        }
+        else {
+            console.error("No Apple signing identity found — physical-device WebDriverAgent signing will fail. " +
+                "Open Xcode → Settings → Accounts to add your Apple ID (see `aximo mobile doctor`).");
+        }
+        const preinstalled = await resolvePreinstalledWdaStrategy(signing, {
+            udid: config.target,
+            iosMajor,
+            log: (message) => console.error(message),
+        });
+        if (preinstalled) {
+            iosSigning = preinstalled;
+            console.error("Using the preinstalled WebDriverAgent (no Xcode build needed).");
+        }
+        else {
+            iosSigning = signing.teamId
+                ? await resolveWdaCaching(signing, { udid: config.target })
+                : signing;
+            if (iosSigning.usePrebuiltWDA)
+                console.error("Reusing the cached WebDriverAgent build.");
+        }
+        // Resolved lazily right before the Appium session is created — a port picked
+        // here would sit unbound (and stealable) until the first remote action.
+        wdaLocalPort = pickFreePort;
+    }
+    // Re-signing can remap bundle ids; launches from the backend use the original.
+    const installedBundleIds = new Map();
+    const rawController = buildController(config, server.endpoint, iosSigning, wdaLocalPort);
+    const controller = config.platform === "ios"
+        ? withBundleIdTranslation(rawController, installedBundleIds)
+        : rawController;
     try {
+        // Warm up the device session before connecting to Aximo so WDA build/signing/
+        // trust problems surface here — with a clear, actionable message — instead of
+        // failing opaquely on the first server-driven action.
+        if (config.platform === "ios") {
+            console.error("Preparing WebDriverAgent on the device…");
+            await controller.screenshot();
+            console.error("Device is ready.");
+        }
         await runControlTunnel({
             wsUrl: getTunnelOrigin(),
             deviceToken: config.deviceToken,
             deviceName: config.name,
             controller,
             installApp: async ({ uploadId }) => {
-                await installUploadedApp({
+                const result = await installUploadedApp({
                     uploadId,
                     platform: config.platform,
                     target: config.target,
+                    log: (message) => console.error(message),
                 });
+                if (result.originalBundleId &&
+                    result.installedBundleId &&
+                    result.originalBundleId !== result.installedBundleId) {
+                    installedBundleIds.set(result.originalBundleId, result.installedBundleId);
+                    console.error(`App re-signed for this device: ${result.originalBundleId} installed as ` +
+                        `${result.installedBundleId}.`);
+                }
             },
         });
     }

package/dist/commands/mobile/connect.js

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+import { mobileErrorHint } from "../../mobile-control/mobile-errors.js";
 import { formatError, printResult } from "../../output.js";
 import { connectWithConfig, resolveDeviceConfig } from "./connect-core.js";
 const IOS_PHYSICAL_WARNING = "Driving a physical iPhone goes through Appium's XCUITest driver, which builds and " +
@@ -29,7 +30,8 @@ export default defineCommand({
             await connectWithConfig(resolved.config);
         }
         catch (error) {
-            printResult(formatError("api_error", error instanceof Error ? error.message : String(error), true));
+            const message = error instanceof Error ? error.message : String(error);
+            printResult(formatError("api_error", message, true, mobileErrorHint(message, resolved.config.platform)));
         }
     },
 });

package/dist/commands/mobile/doctor.d.ts

@@ -15,8 +15,11 @@ export interface MobileDoctorReport {
         info: number;
     };
 }
+export declare function checkIosTunnel(isHealthy?: (port: number) => Promise<boolean>): Promise<Check>;
 export interface RunMobileDoctorOptions {
     platform?: "ios" | "android" | undefined;
+    /** Injectable tunnel probe for tests. */
+    isTunnelHealthy?: (port: number) => Promise<boolean>;
 }
 export declare function runMobileDoctor(options?: RunMobileDoctorOptions): Promise<Envelope<MobileDoctorReport>>;
 declare const _default: import("citty").CommandDef<{

package/dist/commands/mobile/doctor.js

@@ -6,7 +6,8 @@ import { join } from "node:path";
 import { formatSuccess, printResult } from "../../output.js";
 import { importAppium } from "../../mobile-control/appium-import.js";
 import { getAppiumHome, resolveAndroidSdk } from "../../mobile-control/appium-server.js";
-import { resolveIosSigning } from "../../mobile-control/ios-signing.js";
+import { resolveIosSigningAuto } from "../../mobile-control/ios-signing.js";
+import { DEFAULT_TUNNEL_REGISTRY_PORT, isTunnelHealthy } from "../../mobile-control/ios-tunnel.js";
 function which(cmd) {
     const probe = platform() === "win32" ? "where" : "which";
     const result = spawnSync(probe, [cmd], { encoding: "utf-8" });
@@ -78,7 +79,7 @@ function checkAndroid() {
         });
     return checks;
 }
-function checkIos() {
+async function checkIos() {
     if (platform() !== "darwin") {
         return [
             { name: "ios", status: "info", message: "iOS device control is only available on macOS" },
@@ -104,37 +105,66 @@ function checkIos() {
         });
     const idb = which("idb");
     checks.push(idb
-        ? { name: "idb", status: "pass", message: idb }
+        ? { name: "idb", status: "info", message: idb }
         : {
             name: "idb",
-            status: "warn",
-            message: "idb not found",
-            hint: "Install idb (brew install idb-companion && pipx install fb-idb). It's used to discover connected iPhones and install .ipa builds.",
+            status: "info",
+            message: "idb not found (optional)",
+            hint: "Device discovery and installs use Xcode's devicectl; idb is only a fallback. Install it with `brew install idb-companion && pipx install fb-idb` if devicectl can't see your device.",
         });
-    const teamId = resolveIosSigning().teamId;
-    checks.push(teamId
-        ? { name: "ios signing", status: "pass", message: `signing team id is set (${teamId})` }
+    // Zero-config signing: the identity + team come from the keychain; env vars
+    // (AXIMO_IOS_TEAM_ID etc.) are overrides, not requirements.
+    const signing = await resolveIosSigningAuto();
+    checks.push(signing.teamId
+        ? {
+            name: "ios signing",
+            status: "pass",
+            message: signing.identityHash
+                ? `signing identity found (team ${signing.teamId}, WDA id ${signing.wdaBundleId})`
+                : `signing team id set (${signing.teamId}) but no matching keychain identity`,
+        }
         : {
             name: "ios signing",
             status: "warn",
-            message: "no signing team id is set",
-            hint: "Driving a physical iPhone needs an Apple Developer Team ID to sign WebDriverAgent. Set AXIMO_IOS_TEAM_ID (or MobileLink's XCODE_TEAM_ID), and optionally AXIMO_IOS_SIGNING_ID / AXIMO_IOS_WDA_BUNDLE_ID.",
+            message: "no Apple Development signing identity found",
+            hint: "Open Xcode → Settings → Accounts, add your Apple ID, then Manage Certificates → + → Apple Development. A free Apple ID works (with weekly re-signing); AXIMO_IOS_TEAM_ID overrides team selection on multi-team machines.",
         });
     checks.push({
         name: "ios webdriveragent",
         status: "info",
-        message: "Physical iPhones are driven via Appium's XCUITest driver, which builds and installs a WebDriverAgent runner on the device.",
-        hint: "Enable Developer Mode (Settings → Privacy & Security), trust this computer, and ensure the WDA bundle id is backed by a valid provisioning profile.",
+        message: "On iOS 17+ a prebuilt WebDriverAgent is downloaded, re-signed and preinstalled (no Xcode build); older devices fall back to the Xcode build flow.",
+        hint: "One-time on the phone: enable Developer Mode (Settings → Privacy & Security), trust this computer, and trust the developer certificate (Settings → General → VPN & Device Management) after the first install.",
     });
     return checks;
 }
+// The RemoteXPC tunnel is host-level (a registry port), so doctor can probe it
+// without a connected device. `connect` starts it automatically, so a missing
+// tunnel is informational, not a failure.
+export async function checkIosTunnel(isHealthy = isTunnelHealthy) {
+    const running = await isHealthy(DEFAULT_TUNNEL_REGISTRY_PORT);
+    return running
+        ? {
+            name: "ios tunnel",
+            status: "pass",
+            message: `RemoteXPC tunnel running (registry port ${DEFAULT_TUNNEL_REGISTRY_PORT})`,
+        }
+        : {
+            name: "ios tunnel",
+            status: "info",
+            message: "RemoteXPC tunnel not running",
+            hint: "iOS 17+ needs it to reach WebDriverAgent; `aximo mobile connect` starts it automatically (prompts for admin).",
+        };
+}
 export async function runMobileDoctor(options = {}) {
     const checks = [await checkAppium()];
     if (options.platform !== "ios") {
         checks.push(...checkAndroid());
     }
     if (options.platform !== "android") {
-        checks.push(...checkIos());
+        checks.push(...(await checkIos()));
+        if (platform() === "darwin") {
+            checks.push(await checkIosTunnel(options.isTunnelHealthy));
+        }
     }
     const summary = { pass: 0, warn: 0, fail: 0, info: 0 };
     for (const c of checks)

package/dist/commands/mobile/doctor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/mobile/doctor.test.js

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { checkIosTunnel } from "./doctor.js";
+describe("checkIosTunnel", () => {
+    it("passes when the RemoteXPC tunnel is reachable", async () => {
+        const check = await checkIosTunnel(async () => true);
+        expect(check.status).toBe("pass");
+        expect(check.name).toBe("ios tunnel");
+    });
+    it("is informational (not a failure) when the tunnel is down", async () => {
+        const check = await checkIosTunnel(async () => false);
+        expect(check.status).toBe("info");
+        expect(check.hint).toContain("aximo mobile connect");
+    });
+});

package/dist/commands/mobile/install.d.ts

@@ -1,4 +1,6 @@
 import { type ExecFn } from "../../mobile-control/exec.js";
+import { ensureInstallableIpa } from "../../mobile-control/ios-auto-resign.js";
+import { installIosApp } from "../../mobile-control/ios-devicectl.js";
 import type { Envelope } from "../../types.js";
 import type { MobilePlatform } from "./paths.js";
 export interface MobileInstallResult {
@@ -9,6 +11,10 @@ export interface MobileInstallResult {
     udid?: string;
     app: string;
     output: string;
+    /** iOS only: set when the app was auto-re-signed for this device. */
+    resigned?: boolean;
+    originalBundleId?: string;
+    installedBundleId?: string;
 }
 export interface MobileInstallOptions {
     app?: string | undefined;
@@ -18,9 +24,10 @@ export interface MobileInstallOptions {
 }
 /**
  * Install an app on the connected phone: Android `.apk` via `adb install -r`,
- * iOS `.ipa` via `idb install`. The iOS build must be signed for the device.
+ * iOS `.ipa` via devicectl — auto-re-signed for the device first when its
+ * signature doesn't already cover it (disable with AXIMO_IOS_NO_RESIGN).
  */
-export declare function runMobileInstall(options: MobileInstallOptions, exec?: ExecFn): Promise<Envelope<MobileInstallResult>>;
+export declare function runMobileInstall(options: MobileInstallOptions, exec?: ExecFn, ensureInstallable?: typeof ensureInstallableIpa, installIos?: typeof installIosApp): Promise<Envelope<MobileInstallResult>>;
 declare const _default: import("citty").CommandDef<{
     readonly app: {
         readonly type: "string";