feat(ios): launch via XCTest with env vars for hierarchy/tap access (#39)

* feat(proto): add env map to LaunchRequest

* feat(driver): add env param to Launch interface and all implementations

* feat(sidecar): add IosDriverBackend using Maestro IOSDriver + env pass-through

* feat(testrun): launch iOS app via XCTest with env vars instead of simctl

* fix(ios): replace LaunchApp with BootedUDID; simctl launch moved to XCTest path

* test(cli): add tests for ios platform flag and ios-device flag parsing

* fix(sdk-ios): check semaphore wait result; resolve port from args and env; register extractors before start

examples/folio/composeApp/src/iosMain/kotlin/app/folio/MainViewController.kt

@@ -29,11 +29,11 @@ private val backGestureTarget = BackGestureTarget()
 @OptIn(ExperimentalForeignApi::class)
 fun MainViewController(): UIViewController {
     Repository.init()
-    app.folio.sanderling.SanderlingIos.start()
     app.folio.sanderling.AuthSnapshots
     app.folio.sanderling.AccountSnapshots
     app.folio.sanderling.LedgerSnapshots
     app.folio.sanderling.NavigationSnapshots
+    app.folio.sanderling.SanderlingIos.start()
     val vc = ComposeUIViewController { App() }
     val gesture = UIScreenEdgePanGestureRecognizer(
         target = backGestureTarget,

examples/folio/composeApp/src/iosMain/kotlin/app/folio/sanderling/IosPauser.kt

@@ -15,7 +15,8 @@ internal object IosPauser {
             dispatch_semaphore_signal(snapshotReady)
             dispatch_semaphore_wait(resumeGate, dispatch_time(DISPATCH_TIME_NOW, 5_000_000_000L))
         }
-        dispatch_semaphore_wait(snapshotReady, dispatch_time(DISPATCH_TIME_NOW, 5_000_000_000L))
+        val waited = dispatch_semaphore_wait(snapshotReady, dispatch_time(DISPATCH_TIME_NOW, 5_000_000_000L))
+        check(waited == 0L) { "snapshot timed out: main thread did not signal within 5s" }
         return capturedSnapshot
     }
 

examples/folio/composeApp/src/iosMain/kotlin/app/folio/sanderling/SanderlingIos.kt

@@ -15,12 +15,24 @@ object SanderlingIos {
     internal val extractors = mutableMapOf<String, () -> Any?>()
 
     fun start() {
-        val env = NSProcessInfo.processInfo.environment
-        val portStr = env["SANDERLING_PORT"] as? String ?: return
-        val port = portStr.toIntOrNull() ?: return
+        val port = resolvePort() ?: return
         IosAgent.start("127.0.0.1", port)
     }
 
+    private fun resolvePort(): Int? {
+        // Env var set via SIMCTL_CHILD_SANDERLING_PORT (simctl direct launch).
+        (NSProcessInfo.processInfo.environment["SANDERLING_PORT"] as? String)
+            ?.toIntOrNull()?.let { return it }
+        // Launch argument -SANDERLING_PORT <value> (Maestro simctl launch).
+        @Suppress("UNCHECKED_CAST")
+        val args = NSProcessInfo.processInfo.arguments as? List<String> ?: return null
+        val idx = args.indexOfFirst { it == "-SANDERLING_PORT" }
+        if (idx >= 0 && idx + 1 < args.size) {
+            return args[idx + 1].toIntOrNull()
+        }
+        return null
+    }
+
     fun extract(name: String, block: () -> Any?) {
         extractors[name] = block
     }