fix: WDA startup flakiness - warmup + connection drop message (#40)

* feat(ios): add simulator management package

* feat(testrun): add iOS platform path (simctl launch + direct TCP)

* feat(cli): add --ios-device flag and IosDevice option

* feat(sdk-ios): add Kotlin Native iOS SDK (TCP agent + POSIX socket + dispatch pauser)

* feat(folio-ios): wire SanderlingIos.start() in MainViewController

* feat(folio-ios): add test-ios justfile recipe

* fix(sdk-ios): remove unavailable C macros; manual byte swap + no-cast warnings

* fix(testrun): simctl-first launch order for iOS; Maestro init after SDK connects

* feat(proto): add env map to LaunchRequest

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

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

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

* feat(sidecar): wire env map in DriverService + IosDriverBackend in Main

* fix(sidecar): use LocalIOSDevice (WDA+simctl) + stop before relaunch

* fix(sidecar): include exception type in gRPC error description

* fix(sidecar): pick free WDA port instead of hardcoded 9100

Use SocketUtils.nextFreePort to pick a free port in the 22000-23000 range
rather than hardcoding 9100, which only worked if a previous WDA session
left a listener there.

* fix(sdk-ios): check semaphore wait result and throw on snapshot timeout

dispatch_semaphore_wait returns nonzero on timeout; ignoring the return
value caused pauseAndSnapshot to silently return an empty map, sending a
garbage empty STATE frame to the host. Now throws so the agent loop
reconnects instead.

* fix(folio-ios): register snapshot extractors before starting agent

SanderlingIos.start() was called before the snapshot objects were
initialized, so a PAUSE message arriving early produced an empty snapshot.
Move start() to after all extractors are registered.

* chore(ios): remove dead LaunchApp function

LaunchApp had no callers since bff3a49 switched iOS launch to go through
the sidecar driver. Remove the dead code and unused os import.

* test(ios): add unit tests for pickSimulator and iOS flag parsing

Tests for all pickSimulator branches (by name, by UDID, unknown, empty
list, iPhone preference, fallback to first). Also tests BootedUDID on a
canceled context and verifies --platform ios and --ios-device flags are
accepted by parseTestArgs.

* fix(ios): propagate error from BootedUDID instead of silently swallowing

* fix(sidecar): IosDriverBackend.healthy() returns true; WDA liveness checked in open()

* fix(sidecar): warm up WDA after health check to absorb startup race

* fix(runner): surface clear message on WDA connection drop

* docs(testrun): note WDA warmup location above WaitForHealth

* fix(sidecar): extract warmup + add one-shot WDA reconnect on IOException

* fix(runner): fatal on permanent WDA drop during hierarchy fetch

* fix(sidecar): walk cause chain in withReconnect to catch Maestro-wrapped IOException

* fix(sidecar): explicit Unit return in pressKey and waitForIdle withReconnect lambdas

* fix(sidecar): serialize WDA reconnect with ReentrantLock to prevent concurrent xcodebuild races

* fix web examples package config

* Revert "fix web examples package config"

This reverts commit 70c10ade27.

* chore: gitignore built sanderling binary

* fix(hierarchy): parse iOS [x1,y1][x2,y2] bounds + match iOS merged desc labels

* refactor(folio-spec): replace bloated spec with two focused properties

Login is opportunistic. Two concrete properties:
1. every new account starts with balance 0
2. every new txn changes ledger balance by exactly its signed amount

Actions: directed login -> addAccount -> addTxn -> back weighted flow.

internal/hierarchy/hierarchy.go

@@ -183,7 +183,8 @@ func match(element *Element, kind, value string) bool {
 	case "text":
 		return element.Text == value
 	case "desc":
-		return element.Description == value
+		// Exact match, or iOS merged label "desc, child text".
+		return element.Description == value || strings.HasPrefix(element.Description, value+", ")
 	case "descPrefix":
 		return strings.HasPrefix(element.Description, value)
 	default:
@@ -191,21 +192,34 @@ func match(element *Element, kind, value string) bool {
 	}
 }
 
-// boundsPattern matches "[l,t,r,b]" (4-value Maestro format).
+// boundsPattern matches "[l,t,r,b]" (4-value Android/Maestro format).
 var boundsPattern = regexp.MustCompile(`^\[(-?\d+),(-?\d+),(-?\d+),(-?\d+)\]$`)
 
+// boundsPatternTwo matches "[x1,y1][x2,y2]" (iOS XCUITest format).
+var boundsPatternTwo = regexp.MustCompile(`^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$`)
+
 func parseBounds(text string) (Bounds, error) {
-	m := boundsPattern.FindStringSubmatch(text)
-	if m == nil {
-		return Bounds{}, fmt.Errorf("bounds %q: not in [L,T,R,B] form", text)
-	}
-	coords := make([]int, 4)
-	for i := range 4 {
-		v, err := strconv.Atoi(m[i+1])
-		if err != nil {
-			return Bounds{}, err
+	if m := boundsPattern.FindStringSubmatch(text); m != nil {
+		coords := make([]int, 4)
+		for i := range 4 {
+			v, err := strconv.Atoi(m[i+1])
+			if err != nil {
+				return Bounds{}, err
+			}
+			coords[i] = v
 		}
-		coords[i] = v
+		return Bounds{Left: coords[0], Top: coords[1], Right: coords[2], Bottom: coords[3]}, nil
 	}
-	return Bounds{Left: coords[0], Top: coords[1], Right: coords[2], Bottom: coords[3]}, nil
+	if m := boundsPatternTwo.FindStringSubmatch(text); m != nil {
+		coords := make([]int, 4)
+		for i := range 4 {
+			v, err := strconv.Atoi(m[i+1])
+			if err != nil {
+				return Bounds{}, err
+			}
+			coords[i] = v
+		}
+		return Bounds{Left: coords[0], Top: coords[1], Right: coords[2], Bottom: coords[3]}, nil
+	}
+	return Bounds{}, fmt.Errorf("bounds %q: not in [L,T,R,B] or [x1,y1][x2,y2] form", text)
 }

internal/hierarchy/hierarchy_test.go

@@ -164,3 +164,38 @@ func TestAccessibilityTextFallback(t *testing.T) {
 		t.Fatal("expected match via accessibilityText fallback")
 	}
 }
+
+func TestIOSMergedLabel(t *testing.T) {
+	// iOS merges contentDescription with child text: "add_account_button, + Add account"
+	input := `{
+	  "attributes": {"accessibilityText": "add_account_button, + Add account", "bounds": "[20,777][382,825]"},
+	  "children": []
+	}`
+	tree, _ := Parse(input)
+	el := tree.Find("desc:add_account_button")
+	if el == nil {
+		t.Fatal("expected desc: to match iOS merged label")
+	}
+	if el.Bounds.Left != 20 || el.Bounds.Top != 777 || el.Bounds.Right != 382 || el.Bounds.Bottom != 825 {
+		t.Errorf("unexpected bounds: %+v", el.Bounds)
+	}
+}
+
+func TestIOSBoundsFormat(t *testing.T) {
+	input := `{
+	  "attributes": {"accessibilityText": "account_card:abc123, Tim, $100", "bounds": "[20,130][382,202]"},
+	  "children": []
+	}`
+	tree, _ := Parse(input)
+	el := tree.Find("descPrefix:account_card:")
+	if el == nil {
+		t.Fatal("expected descPrefix to match iOS account card")
+	}
+	if el.Bounds.Left != 20 || el.Bounds.Top != 130 || el.Bounds.Right != 382 || el.Bounds.Bottom != 202 {
+		t.Errorf("unexpected bounds: %+v", el.Bounds)
+	}
+	cx, cy := el.Bounds.Center()
+	if cx != 201 || cy != 166 {
+		t.Errorf("unexpected center: (%d, %d)", cx, cy)
+	}
+}