qa-agent-kit 0.6.0__py3-none-any.whl

qakit/tools/device_qa.py

@@ -0,0 +1,838 @@
+#!/usr/bin/env python3
+"""Real-device QA runner: readiness check, Developer Mode, test runs under device-wide variants, screenshots, crashes, hangs,
+upgrades, the Release archive, trait changes, and one lock per phone for many sessions.
+
+The test iPhone is USB-attached to the Mac that runs this script. Protocol and what to run when: docs/device-qa-protocol.md.
+Per-app manifest (docs/manifest.md): `--manifest path/to/device_qa.json`, or `--app <slug>` which resolves
+`<apps-root>/<slug>/release/testing/device_qa.json` (apps-root: --apps-root, $QAKIT_APPS_ROOT, else <git top>/apps).
+
+  python3 tools/device_qa.py doctor --app myapp
+  python3 tools/device_qa.py devmode reveal            # Settings > Privacy & Security > Developer Mode appears
+  python3 tools/device_qa.py test --app myapp --suite ui --variant dark --variant large-text
+  python3 tools/device_qa.py test --app myapp --suite smoke --suite ui --configuration Release
+  python3 tools/device_qa.py shots <bundle.xcresult> --out <dir>
+  python3 tools/device_qa.py crashes --app myapp --since-minutes 60 --out <dir>
+  python3 tools/device_qa.py perf --app myapp --seconds 40                 # Time Profiler attached: potential hangs, hang risks
+  python3 tools/device_qa.py upgrade --app myapp --from myapp/ios/v1.0     # previous release's data survives an in-place upgrade
+  python3 tools/device_qa.py release --app myapp --archive <xcarchive>     # the Release archive, cold-launched with no debugger
+  python3 tools/device_qa.py traits --app myapp --screen map   # text size and dark mode changed in front and in background
+  python3 tools/device_qa.py lock status                    # who holds the test phone, who waits
+  python3 tools/device_qa.py lock run --note "<who>" -- xcodebuild ...   # raw phone work, in turn with the other sessions
+
+One phone, many sessions: every command that drives the phone waits its turn (device_lock.py). QAKIT_DEVICE_NOTE names the
+holder for the others; --no-wait fails fast instead. Needs Xcode 27 or later (`devicectl device settings appearance`).
+Artifacts go to --out, else $QAKIT_ARTIFACTS/<app>/<stamp>, else /tmp/qakit/<app>/<stamp>.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile   # mutation-ok: stdlib import
+from pathlib import Path
+from typing import Any
+
+import hashlib
+
+from device_lock import DeviceBusy, DeviceLock   # same folder: on sys.path as a script and through the tests
+
+XCODE = os.environ.get("DEVELOPER_DIR", "/Applications/Xcode.app/Contents/Developer")   # xcode-select may point at CommandLineTools
+ARTIFACTS = Path(os.environ.get("QAKIT_ARTIFACTS", "/tmp/qakit"))
+VARIANT_KEYS = {"appearance", "text_size", "location", "voiceover", "env"}
+APPEARANCES = {"light", "dark"}
+TEXT_SIZES = {"extra-small", "small", "medium", "large", "extra-large", "extra-extra-large", "extra-extra-extra-large",
+              "accessibility-medium", "accessibility-large", "accessibility-extra-large", "accessibility-extra-extra-large",
+              "accessibility-extra-extra-extra-large"}
+DEFAULTS = {"appearance": "light", "text_size": "large"}   # what a variant run restores, the iOS defaults
+# What a user changes in Settings or Control Center while an app is open or waiting: smallest text, the largest accessibility size,
+# a large standard size, the default, then dark and back. `traits` plays it with each screen in front, then again in the background.
+TRAIT_STEPS = [("text_size", "extra-small"), ("text_size", "accessibility-extra-extra-extra-large"), ("text_size", "extra-extra-extra-large"),
+               ("text_size", "large"), ("appearance", "dark"), ("appearance", "light")]
+SUMMARY = re.compile(r"Executed (\d+) tests?, with (?:(\d+) tests? skipped and )?(\d+) failures?")
+
+
+def tool_env(extra: dict[str, str] | None = None) -> dict[str, str]:
+    """The environment the tools run in: DEVELOPER_DIR set, and that Xcode's usr/bin first on PATH, so the xcrun that xcodebuild
+    itself spawns finds devicectl (its device diagnostics step printed "unable to find utility devicectl" on a Mac whose
+    xcode-select points at CommandLineTools, Daynest 2026-10-29)."""
+    env = os.environ.copy()
+    env.setdefault("DEVELOPER_DIR", XCODE)
+    usr_bin = str(Path(env["DEVELOPER_DIR"]) / "usr/bin")
+    if usr_bin not in env.get("PATH", "").split(":"):
+        env["PATH"] = usr_bin + ":" + env.get("PATH", "")
+    env.update(extra or {})
+    return env
+
+
+def run(cmd: list[str], *, env: dict[str, str] | None = None, timeout: float | None = 120, log: Path | None = None) -> subprocess.CompletedProcess:
+    """Run a tool and capture (or stream to `log`) its output. A tool that does not answer within `timeout` comes back as a
+    failed CompletedProcess (rc 124) with a one-line reason, never as a traceback: `xcrun devicectl list devices` hung for
+    the full two minutes on a Mac whose CoreSimulator was older than Xcode (2026-10-29)."""
+    try:
+        if log:
+            with log.open("w", encoding="utf-8") as handle:
+                return subprocess.run(cmd, env=env or tool_env(), stdout=handle, stderr=subprocess.STDOUT, timeout=timeout, check=False)
+        return subprocess.run(cmd, env=env or tool_env(), capture_output=True, text=True, timeout=timeout, check=False)
+    except subprocess.TimeoutExpired:
+        reason = f"{cmd[0]} did not answer in {timeout:.0f} s" + (" (xcrun devicectl hangs when CoreSimulator is older than Xcode: update Xcode or reboot)"
+                                                                 if "devicectl" in cmd else "")
+        if log:
+            log.write_text(reason + "\n", encoding="utf-8")
+        return subprocess.CompletedProcess(cmd, 124, "", reason)
+
+
+def devicectl_json(args: list[str], timeout: float = 120) -> dict[str, Any]:
+    """`devicectl ... --json-output` as a dict; {} when it failed, {"error": reason} when it hung (the caller shows the reason)."""
+    with tempfile.NamedTemporaryFile(suffix=".json") as out:
+        done = run(["xcrun", "devicectl", *args, "--json-output", out.name], timeout=timeout)
+        if done.returncode == 124:
+            return {"error": done.stderr}
+        try:
+            return json.loads(Path(out.name).read_text(encoding="utf-8") or "{}").get("result", {})
+        except json.JSONDecodeError:
+            return {}
+
+
+# ---- pure helpers (agent/tests/test_device_qa.py) ----
+
+def pick_device(devices: list[dict[str, Any]], udid: str | None = None) -> dict[str, str] | None:
+    """The attached test iPhone from `devicectl list devices` JSON: physical, paired, wired first; `udid` pins one."""
+    found = []
+    for device in devices:
+        hardware, connection = device.get("hardwareProperties", {}), device.get("connectionProperties", {})
+        if hardware.get("reality") == "simulated" or hardware.get("platform", "iOS") != "iOS":
+            continue   # `reality` is missing until a tunnel opens, so only an explicit "simulated" excludes
+        if connection.get("pairingState") != "paired" or not hardware.get("udid"):
+            continue
+        if udid and hardware["udid"] != udid:
+            continue
+        found.append({"udid": hardware["udid"], "name": device.get("deviceProperties", {}).get("name", ""),
+                      "transport": connection.get("transportType", "")})
+    found.sort(key=lambda d: d["transport"] != "wired")
+    return found[0] if found else None
+
+
+def validate_manifest(data: dict[str, Any]) -> list[str]:
+    errors = [f"{key} must be a non-empty string" for key in ("schema_version", "app", "scheme", "process_name")
+              if not isinstance(data.get(key), str) or not data[key].strip()]
+    if not any(isinstance(data.get(key), str) and data[key].strip() for key in ("project", "workspace")):
+        errors.append("project (or workspace) must be a non-empty string")
+    suites = data.get("suites")
+    if not isinstance(suites, dict) or not suites or not all(isinstance(v, list) and v and all(isinstance(t, str) for t in v) for v in suites.values()):
+        errors.append("suites must map a name to a non-empty list of -only-testing identifiers")
+    for name, variant in (data.get("variants") or {}).items():
+        unknown = set(variant) - VARIANT_KEYS
+        if unknown:
+            errors.append(f"variant {name}: unknown keys {sorted(unknown)}")
+        if "appearance" in variant and variant["appearance"] not in APPEARANCES:
+            errors.append(f"variant {name}: appearance must be one of {sorted(APPEARANCES)}")
+        if "text_size" in variant and variant["text_size"] not in TEXT_SIZES:
+            errors.append(f"variant {name}: unknown text_size {variant['text_size']}")
+        location = variant.get("location")
+        if location is not None and not (isinstance(location, list) and len(location) == 2 and all(isinstance(v, (int, float)) for v in location)):
+            errors.append(f"variant {name}: location must be [latitude, longitude]")
+        if not isinstance(variant.get("env", {}), dict):
+            errors.append(f"variant {name}: env must be an object")
+    screens = (data.get("traits") or {}).get("screens", {})
+    if not isinstance(screens, dict) or not all(isinstance(v, list) and all(isinstance(a, str) for a in v) for v in screens.values()):
+        errors.append("traits.screens must map a screen name to its launch arguments")
+    return errors
+
+
+def variant_commands(udid: str, variant: dict[str, Any]) -> list[list[str]]:
+    """devicectl calls that put the whole phone into the variant (every app, system alerts included)."""
+    base = ["xcrun", "devicectl", "device"]
+    cmds = []
+    if "appearance" in variant or "text_size" in variant:
+        cmd = [*base, "settings", "appearance", "--device", udid]
+        if "appearance" in variant:
+            cmd += ["--mode", variant["appearance"]]
+        if "text_size" in variant:
+            # Accessibility sizes only apply with Larger Accessibility Sizes on (devicectl help, 2026-10-28).
+            larger = "on" if variant["text_size"].startswith("accessibility-") else "off"
+            cmd += ["--text-size", variant["text_size"], "--larger-accessibility-sizes", larger]
+        cmds.append(cmd)
+    if variant.get("voiceover"):
+        cmds.append([*base, "settings", "voiceover", "--device", udid, "--enable"])
+    if "location" in variant:
+        lat, lng = variant["location"]
+        cmds.append([*base, "simulate", "location", "coordinate", "--device", udid, "--latitude", str(lat), "--longitude", str(lng)])
+    return cmds
+
+
+def restore_commands(udid: str, variant: dict[str, Any]) -> list[list[str]]:
+    """Undo `variant_commands`, so the next run (or a human) finds the phone in iOS defaults."""
+    base = ["xcrun", "devicectl", "device"]
+    cmds = []
+    if "appearance" in variant or "text_size" in variant:
+        cmds.append([*base, "settings", "appearance", "--device", udid, "--mode", DEFAULTS["appearance"], "--text-size", DEFAULTS["text_size"],
+                     "--larger-accessibility-sizes", "off"])
+    if variant.get("voiceover"):
+        cmds.append([*base, "settings", "voiceover", "--device", udid, "--disable"])
+    if "location" in variant:
+        cmds.append([*base, "simulate", "location", "clear", "--device", udid])
+    return cmds
+
+
+def trait_commands(udid: str) -> list[list[str]]:
+    """One devicectl call per TRAIT_STEPS change (the largest sizes need Larger Accessibility Sizes on, as in variant_commands)."""
+    base = ["xcrun", "devicectl", "device", "settings", "appearance", "--device", udid]
+    return [[*base, "--text-size", value, "--larger-accessibility-sizes", "on" if value.startswith("accessibility-") else "off"]
+            if kind == "text_size" else [*base, "--mode", value] for kind, value in TRAIT_STEPS]
+
+
+def runner_env(name: str, variant: dict[str, Any]) -> dict[str, str]:
+    """xcodebuild forwards TEST_RUNNER_<KEY> to the UI-test runner as <KEY>; QAKit reads QA_VARIANT, QA_LANG, ..."""
+    env = {"TEST_RUNNER_QA_VARIANT": name}
+    env.update({f"TEST_RUNNER_{key}": str(value) for key, value in (variant.get("env") or {}).items()})
+    return env
+
+
+def summarize_log(text: str) -> dict[str, Any]:
+    """The last (outermost) XCTest summary line, and the overall verdict."""
+    hits = SUMMARY.findall(text)
+    executed, skipped, failures = (int(hits[-1][0]), int(hits[-1][1] or 0), int(hits[-1][2])) if hits else (0, 0, 0)
+    failed_cases = sorted(set(re.findall(r"Test Case '-\[(\S+ \S+)\]' failed", text)))
+    succeeded = "** TEST SUCCEEDED **" in text and not failures
+    return {"executed": executed, "skipped": skipped, "failures": failures, "failed_cases": failed_cases, "succeeded": succeeded}
+
+
+def build_index(manifest: list[dict[str, Any]], title: str) -> str:
+    """Markdown contact sheet from `xcresulttool export attachments` manifest.json: one section per test, files in order."""
+    lines = [f"# {title}", ""]
+    for test in manifest:
+        lines.append(f"## {test.get('testIdentifier', '?')}")
+        for item in test.get("attachments", []):
+            name = item.get("exportedFileName", "")
+            # Xcode 27.2's manifest suffixes the readable name with `_<n>_<UUID>.<ext>` (Daynest round 2); the attachment's own name is the step
+            shown = re.sub(r"_\d+_[0-9A-Fa-f-]{36}(\.[A-Za-z0-9]+)?$", "", item.get("suggestedHumanReadableName", name))
+            lines.append(f"- {shown}: `{name}`" + (" (failure)" if item.get("isAssociatedWithFailure") else ""))
+        lines.append("")
+    return "\n".join(lines)
+
+
+def crash_candidates(files: list[dict[str, Any]], process: str | list[str], since: dt.datetime) -> list[str]:
+    """Crash/jetsam reports written since `since` that may concern the app or its extensions (`process` may list several:
+    the app and e.g. its widget extension); jetsam files are checked for the names after copying."""
+    names = [process] if isinstance(process, str) else list(process)
+    picked = []
+    for item in files:
+        path = item.get("relativePath", "")
+        stamp = item.get("metadata", {}).get("lastModDate", "")
+        try:
+            when = dt.datetime.fromisoformat(stamp.replace("Z", "+00:00"))
+        except ValueError:
+            continue
+        if when >= since and path.endswith(".ips") and (any(path.startswith(n) for n in names) or path.startswith("JetsamEvent")):
+            picked.append(path)
+    return picked
+
+
+# ---- commands ----
+
+def git_top(start: Path) -> Path:
+    result = subprocess.run(["git", "-C", str(start), "rev-parse", "--show-toplevel"], capture_output=True, text=True, check=False)
+    return Path(result.stdout.strip()) if result.returncode == 0 else start
+
+
+def manifest_path_for(args: argparse.Namespace) -> Path:
+    if getattr(args, "manifest", None):
+        return Path(args.manifest).resolve()
+    if not getattr(args, "app", None):
+        raise SystemExit("give --manifest <device_qa.json> or --app <slug>")
+    root = Path(getattr(args, "apps_root", None) or os.environ.get("QAKIT_APPS_ROOT") or git_top(Path.cwd()) / "apps")
+    return (root / args.app / "release/testing/device_qa.json").resolve()
+
+
+def load_manifest(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        raise SystemExit(f"no manifest at {path} (docs/manifest.md)")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    errors = validate_manifest(data)
+    if errors:
+        raise SystemExit(f"{path}: " + "; ".join(errors))
+    return data
+
+
+def load_app(args: argparse.Namespace) -> tuple[Path, dict[str, Any]]:
+    path = manifest_path_for(args)
+    return path, load_manifest(path)
+
+
+def store_config(manifest_path: Path, data: dict[str, Any]) -> dict[str, Any]:
+    """The app's store config JSON (`appstore_config`), {} when the manifest has none."""
+    if not data.get("appstore_config"):
+        return {}
+    return json.loads((manifest_path.parent / data["appstore_config"]).resolve().read_text(encoding="utf-8"))
+
+
+def bundle_id(manifest_path: Path, data: dict[str, Any]) -> str:
+    """Manifest `bundle_id`, else the store config's; the installed app's identity for launch, install and uninstall."""
+    value = data.get("bundle_id") or store_config(manifest_path, data).get("bundle_id")
+    if not value:
+        raise SystemExit("the manifest needs bundle_id (or an appstore_config with one)")
+    return value
+
+
+def team_id(manifest_path: Path, data: dict[str, Any]) -> str:
+    value = data.get("team_id") or store_config(manifest_path, data).get("team_id")
+    if not value:
+        raise SystemExit("the manifest needs team_id (or an appstore_config with one)")
+    return value
+
+
+def project_args(manifest_path: Path, data: dict[str, Any]) -> list[str]:
+    if data.get("workspace"):
+        return ["-workspace", str((manifest_path.parent / data["workspace"]).resolve())]
+    return ["-project", str((manifest_path.parent / data["project"]).resolve())]
+
+
+def app_root(manifest_path: Path, data: dict[str, Any]) -> Path:
+    """The app's folder: what the project or workspace lives in (build output and the source fingerprint are relative to it)."""
+    return (manifest_path.parent / (data.get("workspace") or data["project"])).resolve().parent
+
+
+def derived_data(manifest_path: Path, data: dict[str, Any], suffix: str = "") -> Path:
+    base = (manifest_path.parent / data["derived_data"]).resolve() if data.get("derived_data") else app_root(manifest_path, data) / "build/DerivedData-device"
+    return Path(str(base) + suffix)
+
+
+def signing_args(manifest_path: Path, data: dict[str, Any]) -> list[str]:
+    """Automatic development signing. With an App Store Connect API key (manifest `signing` block, or the `api` block of the
+    `appstore_config` JSON) xcodebuild registers the phone and mints profiles with no Xcode login; without one it relies on
+    the Mac's Xcode account. The key path is absolute, or relative to the manifest's git top level, else under $QAKIT_SECRETS_ROOT."""
+    args = ["-allowProvisioningUpdates", "-allowProvisioningDeviceRegistration"]
+    signing = data.get("signing")
+    if not signing and data.get("appstore_config"):
+        api = store_config(manifest_path, data).get("api", {})
+        signing = {"key_path": api.get("private_key_path"), "key_id": api.get("key_id"), "issuer_id": api.get("issuer_id")}
+    if not signing or not signing.get("key_path"):
+        return args
+    key = Path(signing["key_path"]).expanduser()
+    if not key.is_absolute():
+        top = git_top(manifest_path.parent)
+        key = top / key
+        if not key.is_file() and os.environ.get("QAKIT_SECRETS_ROOT"):
+            key = Path(os.environ["QAKIT_SECRETS_ROOT"]) / signing["key_path"]
+    return [*args, "-authenticationKeyPath", str(key), "-authenticationKeyID", signing["key_id"], "-authenticationKeyIssuerID", signing["issuer_id"]]
+
+
+LAST_DEVICE_ERROR = ""   # why the last `find_device` found nothing when devicectl itself failed (a hang), for doctor's message
+
+
+def manual_signing_problems(manifest_path: Path, data: dict[str, Any]) -> list[str]:
+    """A project that pins App Store provisioning profiles (manual signing) cannot be signed for a test phone with the
+    development certificate the ASC key mints: Daynest's first device run died on "profile doesn't include signing
+    certificate Apple Development" (2026-10-29). The fix is build-setting overrides in the manifest's `xcodebuild_args`."""
+    if any(str(a).startswith("CODE_SIGN_STYLE=") for a in data.get("xcodebuild_args", [])):
+        return []
+    project = (manifest_path.parent / (data.get("workspace") or data["project"])).resolve()
+    pbxproj = project / "project.pbxproj" if project.suffix == ".xcodeproj" else None
+    if not pbxproj or not pbxproj.is_file():
+        return []
+    text = pbxproj.read_text(encoding="utf-8", errors="replace")
+    if "CODE_SIGN_STYLE = Manual" in text and "PROVISIONING_PROFILE_SPECIFIER = \"" in text:
+        return ['the project pins provisioning profiles (CODE_SIGN_STYLE = Manual): add to the manifest '
+                '"xcodebuild_args": ["CODE_SIGN_STYLE=Automatic", "PROVISIONING_PROFILE_SPECIFIER=", '
+                '"CODE_SIGN_IDENTITY=Apple Development", "DEVELOPMENT_TEAM=<team id>"] so device runs sign with a development profile']
+    return []
+
+
+def find_device(udid: str | None) -> dict[str, str] | None:
+    global LAST_DEVICE_ERROR
+    listing = devicectl_json(["list", "devices"])
+    LAST_DEVICE_ERROR = str(listing.get("error") or "")
+    return pick_device(listing.get("devices", []), udid)
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    problems: list[str] = []
+    device = find_device(args.udid)
+    if not device:
+        print(LAST_DEVICE_ERROR or "device: none paired. Plug the iPhone into this Mac, unlock it, tap Trust.")
+        if args.app or args.manifest:
+            manifest_path = manifest_path_for(args)
+            load_manifest(manifest_path)   # a manifest mistake shows even without a phone
+            print(f"manifest: {manifest_path} loads")
+        return 1
+    details = devicectl_json(["device", "info", "details", "--device", device["udid"]]).get("deviceProperties", {})
+    lock = run(["xcrun", "devicectl", "device", "info", "lockState", "--device", device["udid"]]).stdout
+    print(f"device: {device['name']} {device['udid']} {device['transport']} iOS {details.get('osVersionNumber')}")
+    if details.get("developerModeStatus") != "enabled":
+        problems.append("Developer Mode is off: `device_qa.py devmode reveal`, then Settings > Privacy & Security > Developer Mode")
+    if "passcodeRequired: true" in lock:
+        problems.append("passcode is set: UI automation will stop for it; turn the passcode off on a test phone")
+    if not details.get("ddiServicesAvailable"):
+        problems.append("developer disk image not mounted yet (it mounts once Developer Mode is on and the phone is unlocked)")
+    identities = run(["security", "find-identity", "-v", "-p", "codesigning"]).stdout
+    if "Apple Development" not in identities:
+        problems.append("no Apple Development identity in the login keychain")
+    keychain = run(["security", "show-keychain-info", str(Path.home() / "Library/Keychains/login.keychain-db")])
+    if "User interaction is not allowed" in keychain.stdout + keychain.stderr:
+        # codesign answers errSecInternalComponent from an ssh or cron session whose login keychain is locked (Daynest, 2026-10-29)
+        problems.append("the login keychain is locked for this session (codesign will fail with errSecInternalComponent): run from the "
+                        "user's GUI session, e.g. a `launchctl bootstrap gui/$UID` LaunchAgent, or unlock the keychain")
+    if args.app or args.manifest:
+        manifest_path, data = load_app(args)
+        problems += manual_signing_problems(manifest_path, data)
+        signing = signing_args(manifest_path, data)
+        if "-authenticationKeyPath" in signing:
+            key = Path(signing[signing.index("-authenticationKeyPath") + 1])
+            if not key.is_file():
+                problems.append(f"App Store Connect key missing: {key}")
+        else:
+            print("signing: no App Store Connect key in the manifest; xcodebuild will use the Mac's Xcode account")
+    for line in problems:
+        print("problem:", line)
+    print("ready" if not problems else f"{len(problems)} problem(s)")
+    return 0 if not problems else 1
+
+
+def cmd_devmode(args: argparse.Namespace) -> int:
+    device = find_device(args.udid)
+    if not device:
+        print("no paired device")
+        return 1
+    result = run(["idevicedevmodectl", "-u", device["udid"], args.action], timeout=300)   # brew install libimobiledevice
+    print((result.stdout + result.stderr).strip())
+    return result.returncode
+
+
+def cmd_test(args: argparse.Namespace) -> int:
+    manifest_path, data = load_app(args)
+    device = find_device(args.udid)
+    if not device:
+        print("no paired device; run doctor")
+        return 1
+    variants = data.get("variants", {})
+    names = args.variant or ["default"]
+    stamp = dt.datetime.now().strftime("%Y%m%d-%H%M%S")
+    out = Path(args.out or ARTIFACTS / data["app"] / stamp)
+    out.mkdir(parents=True, exist_ok=True)
+    started = dt.datetime.now(dt.timezone.utc)
+    build_dirs = [derived_data(manifest_path, data), derived_data(manifest_path, data, "-release")]
+    tree_before = tree_fingerprint(fingerprint_root(manifest_path, data), build_dirs)
+    report: list[dict[str, Any]] = []
+    for name in names:
+        variant = variants.get(name, {}) if name != "default" else variants.get("default", {})
+        if name != "default" and name not in variants:
+            raise SystemExit(f"unknown variant {name}; known: {sorted(variants)}")
+        for cmd in variant_commands(device["udid"], variant):
+            run(cmd)
+        try:
+            for suite in (["only"] if args.only else args.suite or ["ui"]):
+                if suite != "only" and suite not in data["suites"]:
+                    raise SystemExit(f"unknown suite {suite}; known: {sorted(data['suites'])}")
+                tests = args.only if suite == "only" else data["suites"][suite]   # --only: single tests while iterating on one defect
+                only = [f"-only-testing:{t}" for t in tests]
+                bundle = out / f"{name}-{suite}.xcresult"
+                log = out / f"{name}-{suite}.log"
+                release = args.configuration == "Release"   # exit criterion 2: the optimized build users get, not only Debug
+                cmd = ["xcodebuild", *project_args(manifest_path, data), "-scheme", data["scheme"], "-destination", f"id={device['udid']}",
+                       "-configuration", args.configuration,
+                       "-derivedDataPath", str(derived_data(manifest_path, data, "-release" if release else "")),
+                       "-resultBundlePath", str(bundle), *signing_args(manifest_path, data), *data.get("xcodebuild_args", []), *only, "test",
+                       *(["ENABLE_TESTABILITY=YES"] if release else [])]   # the scheme builds the @testable unit target too
+                run(cmd, env=tool_env(runner_env(name, variant)), timeout=args.timeout, log=log)
+                summary = summarize_log(log.read_text(encoding="utf-8", errors="replace"))
+                shots = export_shots(bundle, out / f"{name}-{suite}-shots", f"{data['app']} {name} {suite}") if bundle.exists() else 0
+                report.append({"variant": name, "suite": suite, **summary, "screenshots": shots, "log": str(log), "xcresult": str(bundle)})
+                print(f"{name}/{suite}: executed {summary['executed']} skipped {summary['skipped']} failures {summary['failures']} shots {shots}"
+                      + ("" if summary["succeeded"] else "  FAILED " + ", ".join(summary["failed_cases"][:5])))
+        finally:
+            for cmd in restore_commands(device["udid"], variant):
+                run(cmd)
+    crashes = pull_crashes(device["udid"], [data["process_name"], *data.get("extension_processes", [])], started, out / "crashes")
+    tainted = tree_changed(fingerprint_root(manifest_path, data), tree_before, "test run", build_dirs)
+    verdict = all(r["succeeded"] for r in report) and not crashes and not tainted
+    (out / "summary.json").write_text(json.dumps({"schema": "qakit.device-qa.summary.v1", "app": data["app"], "device": device,
+                                                  "started": started.isoformat(), "runs": report, "crashes": crashes,
+                                                  "sources_changed_during_run": tainted, "succeeded": verdict},
+                                                 ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"crashes: {len(crashes)}  artifacts: {out}")
+    return 0 if verdict else 1
+
+
+def fingerprint_root(manifest_path: Path, data: dict[str, Any]) -> Path:
+    """Where a source edit counts as a changed tree: manifest `fingerprint_root` (an app whose core lives beside the project
+    folder, Elsewhen 2026-10-28), else the project folder."""
+    return (manifest_path.parent / data["fingerprint_root"]).resolve() if data.get("fingerprint_root") else app_root(manifest_path, data)
+
+
+def tree_fingerprint(app_dir: Path, exclude: list[Path] = ()) -> str:
+    """What the app's sources look like right now: tracked changes against HEAD plus untracked files. A phone round whose
+    fingerprint differs at the end compiled a mix of before and after (an edit landed mid-build and the round died with a
+    compile error twice on 2026-10-28), so its results describe no single tree."""
+    root = git_top(app_dir)
+    rel = str(app_dir.resolve().relative_to(root)) if app_dir.resolve().is_relative_to(root) else str(app_dir)
+    # Markdown never compiles: a QA ledger written during a round (docs/qa/QA_*.md) does not make it a mixed round (2026-10-28).
+    spec = ["--", rel, f":(glob,exclude){rel}/**/*.md"]
+    for folder in exclude:   # the run's own build output (DerivedData next to the project, when it is not gitignored) is not a source edit
+        folder = folder.resolve()
+        if folder.is_relative_to(root):
+            spec.append(f":(exclude){folder.relative_to(root)}")
+    status = subprocess.run(["git", "-C", str(root), "status", "--porcelain", *spec], capture_output=True, text=True).stdout
+    diff = subprocess.run(["git", "-C", str(root), "diff", "HEAD", *spec], capture_output=True, text=True).stdout
+    return hashlib.sha1((status + diff).encode("utf-8", "replace")).hexdigest()
+
+
+def tree_changed(app_dir: Path, before: str, what: str, exclude: list[Path] = ()) -> bool:
+    """True (and a loud warning) when the sources changed while `what` was running."""
+    if tree_fingerprint(app_dir, exclude) == before:
+        return False
+    print(f"WARNING: sources under {app_dir.name} changed while the {what} was running; its results mix two trees. Re-run.")
+    return True
+
+
+def export_shots(bundle: Path, out: Path, title: str) -> int:
+    out.mkdir(parents=True, exist_ok=True)
+    run(["xcrun", "xcresulttool", "export", "attachments", "--path", str(bundle), "--output-path", str(out)], timeout=600)
+    manifest_file = out / "manifest.json"
+    manifest = json.loads(manifest_file.read_text(encoding="utf-8")) if manifest_file.is_file() else []
+    (out / "index.md").write_text(build_index(manifest, title), encoding="utf-8")
+    return sum(len(t.get("attachments", [])) for t in manifest)
+
+
+def pull_crashes(udid: str, process: str | list[str], since: dt.datetime, out: Path) -> list[str]:
+    names = [process] if isinstance(process, str) else list(process)
+    files = devicectl_json(["device", "info", "files", "--device", udid, "--domain-type", "systemCrashLogs"]).get("files", [])
+    kept = []
+    for relative in crash_candidates(files, process, since):
+        out.mkdir(parents=True, exist_ok=True)
+        target = out / Path(relative).name
+        run(["xcrun", "devicectl", "device", "copy", "from", "--device", udid, "--domain-type", "systemCrashLogs",
+             "--source", relative, "--destination", str(target)])
+        text = target.read_text(encoding="utf-8", errors="replace") if target.is_file() else ""
+        if any(relative.startswith(n) or f'"{n}"' in text for n in names):   # a jetsam report counts only when it names one
+            kept.append(str(target))
+        elif target.is_file():
+            target.unlink()
+    return kept
+
+
+def cmd_shots(args: argparse.Namespace) -> int:
+    count = export_shots(Path(args.xcresult), Path(args.out), Path(args.xcresult).stem)
+    print(f"{count} attachments -> {args.out}/index.md")
+    return 0
+
+
+def trace_rows(xml_text: str) -> list[dict[str, str]]:
+    """Rows of one exported Instruments table (`xctrace export --xpath ...table[@schema=X]`), refs resolved, as {column: fmt}."""
+    import xml.etree.ElementTree as ET
+    root = ET.fromstring(xml_text) if xml_text.strip() else None
+    if root is None:
+        return []
+    columns = [c.findtext("mnemonic") or "" for c in root.iter("col")]
+    seen: dict[str, str] = {}
+    for el in root.iter():
+        if el.get("id"):
+            seen[el.get("id")] = el.get("fmt") or (el.text or "")
+    rows = []
+    for row in root.iter("row"):
+        values = [c.get("fmt") or seen.get(c.get("ref") or "", "") or (c.text or "") for c in row]
+        rows.append(dict(zip(columns, values)))
+    return rows
+
+
+def cmd_perf(args: argparse.Namespace) -> int:
+    """PERF-05: launch the installed app, attach Time Profiler for --seconds, report Instruments' potential hangs and hang risks.
+    `xctrace record --launch` waits for a 'boot' that never comes on an iOS newer than Xcode's SDK (27.2 vs 27.1), so it attaches."""
+    manifest_path, data = load_app(args)
+    device = find_device(args.udid)
+    if not device:
+        print("no paired device")
+        return 1
+    bundle = bundle_id(manifest_path, data)
+    out = Path(args.out or ARTIFACTS / data["app"] / ("perf-" + dt.datetime.now().strftime("%Y%m%d-%H%M%S")))
+    out.mkdir(parents=True, exist_ok=True)
+    trace = out / "launch.trace"
+    variant = data.get("variants", {}).get(args.variant, {}) if args.variant else {}
+    if args.variant and not variant:
+        raise SystemExit(f"unknown variant {args.variant}")
+    for cmd in variant_commands(device["udid"], variant):   # e.g. VoiceOver on: an assistive technology walks the whole tree
+        run(cmd)
+    try:
+        launch_args = ["--", *args.arg] if args.arg else []
+        run(["xcrun", "devicectl", "device", "process", "launch", "--device", device["udid"], "--terminate-existing", bundle, *launch_args])
+        run(["xcrun", "xctrace", "record", "--template", "Time Profiler", "--device", device["udid"], "--time-limit", f"{args.seconds}s",
+             "--output", str(trace), "--attach", data["process_name"]], timeout=args.seconds + 180)
+    finally:
+        for cmd in restore_commands(device["udid"], variant):
+            run(cmd)
+    report = {}
+    for schema in ("potential-hangs", "hang-risks"):
+        xml_text = run(["xcrun", "xctrace", "export", "--input", str(trace), "--xpath", f'/trace-toc/run/data/table[@schema="{schema}"]'],
+                       timeout=600).stdout
+        report[schema] = trace_rows(xml_text)
+        print(f"{schema}: {len(report[schema])}" + "".join(f"\n  {r.get('duration', '')} {r.get('hang-type', '')} {r.get('thread', '')[:60]}" for r in report[schema][:10]))
+    (out / "perf.json").write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"trace: {trace}")
+    return 1 if report["potential-hangs"] else 0
+
+
+def cmd_upgrade(args: argparse.Namespace) -> int:
+    """BUILD-04: the previous release's data survives an in-place upgrade. A temporary worktree at --from builds the old app, the
+    manifest's seed test (copied in, black-box) leaves real-user data on the phone, this build installs over it and the check test
+    runs with QA_UPGRADE=1. The app is uninstalled first so the seed starts from nothing; the worktree is removed afterwards."""
+    manifest_path, data = load_app(args)
+    cfg = data["upgrade"]
+    device = find_device(args.udid)
+    if not device:
+        print("no paired device")
+        return 1
+    app_dir = app_root(manifest_path, data)
+    root = git_top(app_dir)
+    project_rel = (manifest_path.parent / (data.get("workspace") or data["project"])).resolve().relative_to(app_dir)
+    bundle = bundle_id(manifest_path, data)
+    out = Path(args.out or ARTIFACTS / data["app"] / ("upgrade-" + dt.datetime.now().strftime("%Y%m%d-%H%M%S")))
+    out.mkdir(parents=True, exist_ok=True)
+    old_repo = out / "old-repo"
+    added = run(["git", "-C", str(root), "worktree", "add", "--detach", str(old_repo), args.from_ref], timeout=600)
+    if added.returncode:
+        print(added.stderr.strip())
+        return 1
+    try:
+        old_app = old_repo / app_dir.relative_to(root)
+        seed_src = (manifest_path.parent / cfg["seed_file"]).resolve()
+        (old_app / cfg["uitests_dir"] / seed_src.name).write_text(seed_src.read_text(encoding="utf-8"), encoding="utf-8")
+        for rel in cfg.get("copy", []):   # gitignored files the old build needs (keys)
+            if (app_dir / rel).is_file():
+                (old_app / rel).write_bytes((app_dir / rel).read_bytes())
+        if cfg.get("generator"):
+            run([sys.executable, str(old_app / cfg["generator"])], timeout=300)
+        run(["xcrun", "devicectl", "device", "uninstall", "app", "--device", device["udid"], bundle])
+        steps = [("old-seed", old_app / project_rel, out / "dd-old", cfg["seed"], {}),
+                 ("new-check", app_dir / project_rel, derived_data(manifest_path, data), cfg["check"], {"TEST_RUNNER_QA_UPGRADE": "1"})]
+        ok = True
+        for name, project, derived, test, env in steps:
+            bundle_path, log = out / f"{name}.xcresult", out / f"{name}.log"
+            flag = "-workspace" if project.suffix == ".xcworkspace" else "-project"
+            run(["xcodebuild", flag, str(project), "-scheme", data["scheme"], "-destination", f"id={device['udid']}",
+                 "-derivedDataPath", str(derived), "-resultBundlePath", str(bundle_path), *signing_args(manifest_path, data),
+                 *data.get("xcodebuild_args", []), f"-only-testing:{test}", "test"], env=tool_env(env), timeout=args.timeout, log=log)
+            summary = summarize_log(log.read_text(encoding="utf-8", errors="replace"))
+            shots = export_shots(bundle_path, out / f"{name}-shots", f"{data['app']} upgrade {name}") if bundle_path.exists() else 0
+            print(f"{name} ({test}): executed {summary['executed']} skipped {summary['skipped']} failures {summary['failures']} shots {shots}")
+            ok = ok and summary["succeeded"] and summary["executed"] > summary["skipped"]   # a skipped check is not a pass
+            if not ok:
+                break
+    finally:
+        run(["git", "-C", str(root), "worktree", "remove", "--force", str(old_repo)], timeout=600)
+    print(("upgrade kept the data" if ok else "UPGRADE FAILED") + f"  artifacts: {out}")
+    return 0 if ok else 1
+
+
+def export_options(team_id: str, cloudkit_env: str) -> dict[str, Any]:
+    """ExportOptions for installing the exact Release archive on the test phone: development signing ('debugging', the old
+    'development'), the CloudKit environment chosen explicitly so a production round trip can be tested before TestFlight."""
+    return {"method": "debugging", "signingStyle": "automatic", "teamID": team_id, "iCloudContainerEnvironment": cloudkit_env,
+            "compileBitcode": False, "stripSwiftSymbols": True}
+
+
+def app_pid(process_list: str, process: str) -> str | None:
+    """`devicectl device info processes` text: the pid of `<process>.app/<process>`, None when it is not running."""
+    return next((line.split()[0] for line in process_list.splitlines() if line.rstrip().endswith(f"/{process}.app/{process}")), None)
+
+
+def app_running(process_list: str, process: str) -> bool:
+    return app_pid(process_list, process) is not None
+
+
+def cmd_release(args: argparse.Namespace) -> int:
+    """BUILD-01: the Release archive itself, exported for the test phone, cold-launched --launches times with no debugger attached.
+    Each launch: alive after --wait seconds, a screenshot; then crash/jetsam reports since the first launch."""
+    import plistlib
+    import time
+    manifest_path, data = load_app(args)
+    device = find_device(args.udid)
+    if not device:
+        print("no paired device")
+        return 1
+    bundle = bundle_id(manifest_path, data)
+    out = Path(args.out or ARTIFACTS / data["app"] / ("release-" + dt.datetime.now().strftime("%Y%m%d-%H%M%S")))
+    out.mkdir(parents=True, exist_ok=True)
+    options = out / "ExportOptions-debugging.plist"
+    options.write_bytes(plistlib.dumps(export_options(team_id(manifest_path, data), args.cloudkit)))
+    exported = run(["xcodebuild", "-exportArchive", "-archivePath", args.archive, "-exportPath", str(out / "export"),
+                    "-exportOptionsPlist", str(options), *signing_args(manifest_path, data)], timeout=1800, log=out / "export.log")
+    ipa = next((out / "export").glob("*.ipa"), None)
+    if exported.returncode or not ipa:
+        print(f"export failed: {out / 'export.log'}")
+        return 1
+    installed = run(["xcrun", "devicectl", "device", "install", "app", "--device", device["udid"], str(ipa)], timeout=600)
+    if installed.returncode:
+        print((installed.stdout + installed.stderr).strip()[-400:])
+        return 1
+    started = dt.datetime.now(dt.timezone.utc)
+    alive = []
+    for i in range(1, args.launches + 1):
+        run(["xcrun", "devicectl", "device", "process", "launch", "--device", device["udid"], "--terminate-existing", bundle])
+        time.sleep(args.wait)
+        processes = run(["xcrun", "devicectl", "device", "info", "processes", "--device", device["udid"]]).stdout
+        alive.append(app_running(processes, data["process_name"]))
+        run(["xcrun", "devicectl", "device", "capture", "screenshot", "--device", device["udid"], "--destination", str(out / f"launch-{i}.png")])
+        print(f"launch {i}: {'running' if alive[-1] else 'NOT RUNNING'}  screenshot {out / f'launch-{i}.png'}")
+    time.sleep(5)   # ReportCrash writes a few seconds after the process dies
+    crashes = pull_crashes(device["udid"], [data["process_name"], *data.get("extension_processes", [])], started, out / "crashes")
+    print(f"{sum(alive)}/{len(alive)} launches alive, crashes {len(crashes)}  ipa {ipa.name}  artifacts {out}")
+    return 0 if all(alive) and not crashes else 1
+
+
+def cmd_traits(args: argparse.Namespace) -> int:
+    """INT-06: for each manifest screen, TRAIT_STEPS with the screen in front, then again with Settings in front. iOS asks a waiting
+    app to redraw its snapshot after each change and kills it when that takes over 10 s (0x8BADF00D scene-update): Pawday's map
+    looped there on the largest text size (2026-10-28). A screen passes when the process that took the changes is still the one
+    running on return; the run passes when no crash report was written either. The phone goes back to light and large text."""
+    import time
+    manifest_path, data = load_app(args)
+    device = find_device(args.udid)
+    if not device:
+        print("no paired device")
+        return 1
+    udid, process = device["udid"], data["process_name"]
+    bundle = bundle_id(manifest_path, data)
+    screens = (data.get("traits") or {}).get("screens") or {"launch": []}
+    screens = {k: v for k, v in screens.items() if not args.screen or k in args.screen}
+    out = Path(args.out or ARTIFACTS / data["app"] / ("traits-" + dt.datetime.now().strftime("%Y%m%d-%H%M%S")))
+    out.mkdir(parents=True, exist_ok=True)
+    pid = lambda: app_pid(run(["xcrun", "devicectl", "device", "info", "processes", "--device", udid]).stdout, process)
+    started = dt.datetime.now(dt.timezone.utc)
+    failed = []
+    for name, launch_args in screens.items():
+        run(["xcrun", "devicectl", "device", "process", "launch", "--device", udid, "--terminate-existing", bundle, *(["--", *launch_args] if launch_args else [])])
+        time.sleep(args.wait)
+        before = pid()
+        for phase in ("front", "background"):
+            if phase == "background":
+                run(["xcrun", "devicectl", "device", "process", "launch", "--device", udid, "com.apple.Preferences"])
+                time.sleep(4)
+            for cmd in trait_commands(udid):
+                run(cmd)
+                time.sleep(args.step)
+        run(["xcrun", "devicectl", "device", "process", "launch", "--device", udid, bundle])   # back in front, no relaunch
+        time.sleep(4)
+        after = pid()
+        run(["xcrun", "devicectl", "device", "capture", "screenshot", "--device", udid, "--destination", str(out / f"{name}.png")])
+        survived = before is not None and before == after
+        print(f"{name}: {'survived' if survived else 'KILLED (relaunched or gone)'}  pid {before} -> {after}")
+        if not survived:
+            failed.append(name)
+    for cmd in restore_commands(udid, dict(DEFAULTS)):
+        run(cmd)
+    time.sleep(5)   # ReportCrash writes a few seconds after the process dies
+    crashes = pull_crashes(udid, [process, *data.get("extension_processes", [])], started, out / "crashes")
+    print(f"{len(screens) - len(failed)}/{len(screens)} screens survived, crashes {len(crashes)}  artifacts {out}")
+    return 0 if not failed and not crashes else 1
+
+
+def cmd_crashes(args: argparse.Namespace) -> int:
+    _, data = load_app(args)
+    device = find_device(args.udid)
+    if not device:
+        print("no paired device")
+        return 1
+    since = dt.datetime.now(dt.timezone.utc) - dt.timedelta(minutes=args.since_minutes)
+    crashes = pull_crashes(device["udid"], [data["process_name"], *data.get("extension_processes", [])], since, Path(args.out))
+    print("\n".join(crashes) or "no crashes")
+    return 1 if crashes else 0
+
+
+DEVICE_COMMANDS = {"test", "perf", "upgrade", "release", "traits", "devmode", "lock"}   # these drive the phone: one session at a time
+
+
+def add_manifest_args(parser: argparse.ArgumentParser) -> None:
+    """--manifest or --app (+ --apps-root); manifest_path_for raises when a command needs one and both are missing."""
+    parser.add_argument("--manifest", help="path to device_qa.json")
+    parser.add_argument("--app", help="app slug under --apps-root")
+    parser.add_argument("--apps-root", help="folder that holds <slug>/release/testing/device_qa.json (default $QAKIT_APPS_ROOT or <git top>/apps)")
+
+
+def cmd_lock(args: argparse.Namespace) -> int:
+    """`status`: who holds the phone and who waits. `run`: hold it around a raw command (main() took the lock already)."""
+    if args.action == "run":
+        command = args.cmd[1:] if args.cmd[:1] == ["--"] else args.cmd
+        return subprocess.call(command) if command else 2
+    device = find_device(args.udid)
+    lock = DeviceLock(device["udid"] if device else (args.udid or "no-device"), "")
+    print("held by " + lock.describe(lock.holder()) if lock.holder() else "free")
+    for i, ticket in enumerate(lock.waiting(), 1):
+        print(f"  {i}. waiting: {lock.describe(ticket)}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--udid", help="pin one device (default: the paired physical iPhone, wired first)")
+    parser.add_argument("--no-wait", action="store_true", help="fail (exit 75) instead of waiting when another session holds the phone")
+    parser.add_argument("--wait-timeout", type=float, default=4 * 3600, help="seconds to wait for the phone before giving up")
+    sub = parser.add_subparsers(dest="command", required=True)
+    doctor = sub.add_parser("doctor")
+    add_manifest_args(doctor)
+    devmode = sub.add_parser("devmode")
+    devmode.add_argument("action", choices=["list", "reveal", "enable"])
+    test = sub.add_parser("test")
+    add_manifest_args(test)
+    test.add_argument("--suite", action="append", help="suite name from the manifest (repeatable; default ui)")
+    test.add_argument("--variant", action="append", help="variant name from the manifest (repeatable; default 'default')")
+    test.add_argument("--only", action="append", help="test identifier(s) to run instead of suites, e.g. PawdayUITests/PawdayUITests/testX")
+    test.add_argument("--out")
+    test.add_argument("--timeout", type=float, default=3600)
+    test.add_argument("--configuration", choices=["Debug", "Release"], default="Debug", help="Release runs the UI suites on the optimized build")
+    shots = sub.add_parser("shots")
+    shots.add_argument("xcresult")
+    shots.add_argument("--out", required=True)
+    perf = sub.add_parser("perf")
+    add_manifest_args(perf)
+    perf.add_argument("--seconds", type=int, default=40)
+    perf.add_argument("--arg", action="append", default=[], help="launch argument for the app (repeatable), e.g. --arg=-pawdayStart --arg=map")
+    perf.add_argument("--variant", help="manifest variant applied while recording, e.g. voiceover")
+    perf.add_argument("--out")
+    upgrade = sub.add_parser("upgrade")
+    add_manifest_args(upgrade)
+    upgrade.add_argument("--from", dest="from_ref", required=True, help="git ref of the previous release (tag or commit)")
+    upgrade.add_argument("--out")
+    upgrade.add_argument("--timeout", type=float, default=2400)
+    release = sub.add_parser("release")
+    add_manifest_args(release)
+    release.add_argument("--archive", required=True, help="the .xcarchive that is (or will be) uploaded")
+    release.add_argument("--cloudkit", choices=["Production", "Development"], default="Production")
+    release.add_argument("--launches", type=int, default=5)
+    release.add_argument("--wait", type=float, default=8)
+    release.add_argument("--out")
+    traits = sub.add_parser("traits")
+    add_manifest_args(traits)
+    traits.add_argument("--screen", action="append", help="screen name from the manifest's traits.screens (repeatable; default all)")
+    traits.add_argument("--wait", type=float, default=10, help="seconds after launch before the first change")
+    traits.add_argument("--step", type=float, default=4.5, help="seconds after each change")
+    traits.add_argument("--out")
+    crashes = sub.add_parser("crashes")
+    add_manifest_args(crashes)
+    crashes.add_argument("--since-minutes", type=int, default=60)
+    crashes.add_argument("--out", required=True)
+    lock = sub.add_parser("lock")
+    lock.add_argument("action", choices=["status", "run"])
+    lock.add_argument("--note", help="who holds the phone, shown to the sessions that wait")
+    lock.add_argument("cmd", nargs="*", help="run: the command to run while holding the phone, after `--`")   # REMAINDER swallowed --note (found by the kit's tests, 0.2.0)
+    args = parser.parse_args(argv)
+    handler = {"doctor": cmd_doctor, "devmode": cmd_devmode, "test": cmd_test, "shots": cmd_shots, "crashes": cmd_crashes,
+               "perf": cmd_perf, "upgrade": cmd_upgrade, "release": cmd_release, "traits": cmd_traits, "lock": cmd_lock}[args.command]
+    if args.command not in DEVICE_COMMANDS or (args.command == "lock" and args.action == "status"):
+        return handler(args)
+    device = find_device(args.udid)
+    note = (getattr(args, "note", None) or os.environ.get("QAKIT_DEVICE_NOTE")
+            or f"{getattr(args, 'app', None) or 'phone'} {args.command} from {Path.cwd().name}")
+    try:
+        with DeviceLock(device["udid"] if device else (args.udid or "no-device"), note, wait=not args.no_wait, timeout=args.wait_timeout):
+            return handler(args)
+    except DeviceBusy as busy:
+        print(busy)
+        return 75   # EX_TEMPFAIL: try again later
+
+
+if __name__ == "__main__":
+    sys.exit(main())   # mutation-ok: entry point, pytest calls main() directly