release: v0.4.11 — stop hijacking the foreground, fix real-device terminate

kuri could not be run on a machine someone was using. Every Simulator input
command raised Simulator.app first, because CGEventPost(kCGHIDEventTap) injects
into the global event stream and lands wherever focus happens to be. `type` was
worse: it shelled out to AppleScript `keystroke`, which goes to the frontmost
app, so without stealing focus it would have typed into the user's own window.
And `wait-for-ui` polls every 250ms, re-stealing the foreground each time.

Input now goes to Simulator.app by pid via CGEventPostToPid, `type` uses Unicode
CGEvents, the observation commands do not activate at all, and `open-sim` opens
in the background. `--activate` restores the old behaviour per command.

Two real-device bugs, both found by writing the tests:

- `terminate --device` built `devicectl device process terminate --device <udid>
  <bundle-id>`, but devicectl's terminate takes `--pid` and no bundle id, so it
  could only ever die on devicectl's argument parser. `launch --device` now
  surfaces the pid; `terminate` takes `--pid` or resolves a bundle id itself.
- `list-apps --device` silently hid every system app: devicectl's app listing
  defaults to developer apps only and says nothing about it.

Also: `uitree` reported "Simulator.app is not running" when it was running but
had no window, which sent you to restart an app that was already up.

Verified on hardware — 24 passed / 0 failed against an iPhone 16 Pro Max,
54 passed / 0 failed against a booted simulator, 42 unit tests.

The e2e suite now runs in CI on macOS, which is what would have caught the
0.4.6-to-0.4.10 silent `--device` no-op in the first place.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012gzdKWXk7UbHm5TtSGqYBJ

Author: justrach

.github/workflows/ci.yml

@@ -35,6 +35,15 @@ jobs:
       - name: Run tests
         run: zig build test -Doptimize=ReleaseSafe
 
+      - name: Run kuri-mobile tests
+        # kuri-mobile ships in the same tarball but has its own build.zig, so
+        # the root `test` step never reached it. Its platform-independent
+        # half — the adb wire protocol, the devicectl JSON decoding, the tool
+        # registry — is worth checking on Linux too; the macOS-only half is
+        # covered by the mobile-macos job.
+        working-directory: kuri-mobile
+        run: zig build test --summary all -Doptimize=ReleaseSafe
+
       - name: Regression — --help / --version do NOT spawn Chrome (issue #156)
         # Old kuri binaries (≤ v0.1.0) silently fell through to the daemon
         # path on `--help`, launching headless Chrome and binding :8080.
@@ -69,6 +78,93 @@ jobs:
             echo "::endgroup::"
           done
 
+  mobile-macos:
+    # kuri-mobile is the one part of the tree that can be exercised against
+    # real Apple tooling, and GitHub's macOS runners ship Xcode plus iOS
+    # simulator runtimes. Before this job the e2e suite only ever ran by hand,
+    # so nothing caught a regression on the device path — which is exactly how
+    # the silent `--device` no-op survived from 0.4.6 to 0.4.10.
+    #
+    # The suite reports SKIP rather than failing for anything the runner
+    # cannot provide (notably the Accessibility grant that uitree/find/
+    # wait-for-ui need, which no CI runner can give), so it is a stable gate
+    # rather than a flaky one.
+    runs-on: macos-latest
+    defaults:
+      run:
+        working-directory: kuri-mobile
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.17.0-dev.813+2153f8143
+
+      - name: Cache Zig build artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            kuri-mobile/.zig-cache
+            ~/.cache/zig
+          key: zig-mobile-${{ runner.os }}-${{ hashFiles('kuri-mobile/build.zig') }}
+          restore-keys: |
+            zig-mobile-${{ runner.os }}-
+
+      - name: Show toolchain
+        run: |
+          xcode-select -p
+          xcodebuild -version
+          ls "$(xcode-select -p)/usr/bin/devicectl" || echo "no devicectl in the selected toolchain"
+
+      - name: Build
+        run: zig build -Doptimize=ReleaseSafe
+
+      - name: Unit tests
+        run: zig build test --summary all
+
+      - name: Doctor
+        # Exits 3 when it finds blocking problems, which on a runner it will
+        # (no Accessibility grant). Informational only — the assertions live
+        # in the e2e suite.
+        continue-on-error: true
+        run: ./zig-out/bin/kuri-mobile doctor
+
+      - name: Boot a simulator
+        # Deliberately picks and boots through kuri-mobile rather than `xcrun
+        # simctl`. Two reasons: it exercises `ios list-devices` and `ios boot`
+        # for real, and bare `xcrun` resolves through xcode-select — the very
+        # indirection whose failure mode this project exists to avoid. simctl
+        # is then called by absolute path for `bootstatus`, which kuri has no
+        # equivalent for.
+        run: |
+          set -euo pipefail
+          udid=$(./zig-out/bin/kuri-mobile ios list-devices \
+            | awk -F'\t' '$1 == "simulator" && $4 ~ /iPhone/ { print $2; exit }')
+          if [ -z "${udid}" ]; then
+            echo "::error::no iPhone simulator available on this runner"
+            ./zig-out/bin/kuri-mobile ios list-devices
+            exit 1
+          fi
+          echo "booting ${udid}"
+          ./zig-out/bin/kuri-mobile ios boot --udid "${udid}"
+          # simctl reports Booted well before the runtime has finished coming
+          # up, so wait on bootstatus — otherwise the first e2e command races
+          # the boot and fails for a reason unrelated to the change under test.
+          "$(xcode-select -p)/usr/bin/simctl" bootstatus "${udid}" -b
+
+      - name: End-to-end (simulator)
+        run: zig build e2e-ios
+
+      - name: End-to-end (physical device)
+        # No phone is attached to a runner, so this must report SKIP and exit
+        # 0. Running it anyway keeps the device suite compiling and proves its
+        # no-hardware path stays clean — the suite is useless as a local gate
+        # if it has quietly stopped building.
+        run: zig build e2e-ios-device
+
   startup-smoke:
     runs-on: ubuntu-latest
 

CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to kuri are documented here.
 
+## [0.4.11] — 2026-07-25
+
+### Fixes — kuri no longer takes over your machine
+
+Driving the Simulator used to seize the user's foreground window and move their cursor. Every input command called `sim_window.activate` before doing anything, because `CGEventPost(kCGHIDEventTap, …)` injects into the *global* event stream — events land wherever focus happens to be, so Simulator.app had to be raised first for a tap to hit the right thing. That made kuri unusable on a machine somebody is actually working on.
+
+- **Input is delivered to Simulator.app by pid** — `CGEventPostToPid` instead of the global HID tap. Events go straight into Simulator's own queue, so no window is raised and the cursor is never warped. Covers `tap`, `doubletap`, `longpress`, `swipe`, `gesture`, `touch`, `key`, `key-sequence`, `batch`
+- **`type` no longer routes through AppleScript.** It shelled out to System Events `keystroke`, which is delivered to whichever app is frontmost — so `ios type` was doubly hostile: it *had* to steal focus to be correct, and if it ever ran without doing so it would type your text into whatever you had open. Now Unicode `CGEvent`s addressed to the pid, which needs no virtual-keycode table either. `osascript` is gone from this path
+- **`uitree`, `find` and `wait-for-ui` no longer activate at all.** They only read the accessibility tree, which works fine on a background app. `wait-for-ui` was the worst offender — it polls every 250ms, so it re-stole the foreground on every poll for the length of the wait
+- **`button` and `background` no longer activate.** They already used `AXPress`, which never needed focus
+- **`open-sim` launches in the background** (`open -g`). Opening a simulator is a setup step, not a request to be interrupted
+- **`--activate` restores the old behaviour** per command, for the case where a gesture genuinely needs Simulator.app to be key. Off by default
+
+### Fixes — real devices
+
+- **`ios terminate --device` could never have succeeded.** It built `devicectl device process terminate --device <udid> <bundle-id>`, but devicectl's terminate takes `--pid` and accepts no bundle id at all — every invocation died on devicectl's own argument parser. `launch --device` now reads the launched pid from `--json-output` and prints `pid=N`; `terminate --device --pid N` does the direct thing; `terminate --device <bundle-id>` resolves the bundle id to a running pid by matching `device info processes` against the app's on-device bundle URL. A launch that reports success without an identifier is now an error rather than a silent zero, which would later terminate an unrelated process
+- **`ios list-apps --device` silently hid every system app.** `devicectl device info apps` defaults to *developer apps only* and says nothing about it, so a command documented as "list installed apps" returned a handful of entries on a phone with hundreds — and exited 0. Now passes `--include-default-apps --include-app-clips`. The same defaulting broke bundle-id lookups, so terminate-by-bundle-id could not resolve a system app either
+- **`ios list-apps` on the simulator no longer demands `--udid`.** It resolves the booted simulator like `launch`, `screenshot` and `uitree` already did; requiring it made `list-apps` the odd command out for no reason a caller could infer
+
+### Fixes — diagnosis
+
+- **"Simulator.app is not running" when Simulator.app was running.** The accessibility tree hangs off a window, and a device booted with `simctl boot` does not open one — so a running-but-windowless Simulator produced an error that sent you to restart an app that was already up. Now a distinct `SimulatorHasNoWindow` error carrying the actual remedy, and `doctor` reports window presence rather than just the process
+
+### Tests
+
+- **`zig build e2e-ios-device`** — a new end-to-end suite against physically attached hardware: inspection, the install → list-apps → launch → terminate → uninstall round trip both by pid and by bundle id, and assertions that the XCUITest-only commands still refuse cleanly *while a real device is attached*. Skips with a reason when nothing is plugged in, when no bundle id is configured, or when the screen is locked — phones re-lock on their own timeout, and SpringBoard refuses every launch while they are, which is the environment rather than a defect. Verified: **24 passed, 0 failed** against an iPhone 16 Pro Max
+- **A real-device command contract group in `e2e-ios`, needing no hardware.** 21 hermetic cases pinning the silent-success class fixed in 0.4.10: every `--device` command must fail loudly against a fake udid, missing arguments must exit 2 rather than 1, and the XCUITest-only commands must exit 3 with an explanation. Two of them assert the *absence* of devicectl's argument-parser complaint, which is what distinguishes "the device is missing" from "we called devicectl wrong" — the exact bug fixed above
+- **`e2e-ios` now degrades instead of failing** on preconditions a machine cannot supply. The Accessibility grant, a Simulator window and the Xcode toolchain are each probed and skipped with a reason, which is what lets the suite be a CI gate rather than a red build on a runner that can never hold a TCC grant
+- **More simulator coverage** — `list-apps`, `status-bar` override/clear, `ui appearance` set-and-read-back, `set-location`/`reset-location`, `log --last`, `terminate`. Verified: **54 passed, 0 failed** against a booted simulator
+- devicectl's JSON shapes are now unit-tested against fixtures — a missing pid must not decode as 0, and a process match must not be made on a coincidental path prefix (`/var/Demo.appendix` is not inside `/var/Demo.app`)
+
+### CI
+
+- **The e2e suite finally runs in CI.** A new `mobile-macos` job builds kuri-mobile, runs its unit tests, boots a simulator and runs both suites. Until now nothing caught a regression on the device path, which is how the silent `--device` no-op survived from 0.4.6 to 0.4.10
+- It picks and boots the simulator *through kuri-mobile itself* rather than `xcrun simctl` — partly to exercise `list-devices` and `boot` for real, and partly because bare `xcrun` resolves through `xcode-select`, which is the exact indirection whose failure mode this project exists to avoid
+- The job never opens Simulator.app, so it runs headless and the accessibility cases skip
+- kuri-mobile's unit tests now also run on the Linux job; they had their own `build.zig` and the root `test` step never reached them
+
 ## [0.4.10] — 2026-07-25
 
 ### Fixes

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .kuri,
-    .version = "0.4.10",
+    .version = "0.4.11",
     .dependencies = .{
         .quickjs = .{
             .url = "https://github.com/mitchellh/zig-quickjs-ng/archive/main.tar.gz",

kuri-mobile/build.zig

@@ -50,27 +50,67 @@ pub fn build(b: *std.Build) void {
     const test_step = b.step("test", "Run unit tests");
     test_step.dependOn(&b.addRunArtifact(unit_tests).step);
 
-    // End-to-end suite. Kept off `test` on purpose: it drives a real booted
-    // simulator, which CI does not have. It receives the built binary's path
-    // as argv[1] so it exercises exactly the artifact that would ship.
-    const e2e_mod = b.createModule(.{
-        .root_source_file = b.path("src/test/e2e_ios.zig"),
+    // End-to-end suites. Kept off `test` on purpose: they shell out to the
+    // real Xcode toolchain, and most cases need a booted simulator or an
+    // attached phone. Each receives the built binary's path as argv[1] so it
+    // exercises exactly the artifact that would ship.
+    //
+    // 0.17 restricts imports to a module's own path, so the shared helpers
+    // come in as named modules rather than relative paths.
+    const io_mod = b.createModule(.{
+        .root_source_file = b.path("src/common/io.zig"),
         .target = target,
         .optimize = optimize,
         .link_libc = true,
     });
-    // 0.17 restricts imports to a module's own path, so the shared io helpers
-    // come in as a named module rather than a relative path.
-    e2e_mod.addImport("io", b.createModule(.{
-        .root_source_file = b.path("src/common/io.zig"),
+    const harness_mod = b.createModule(.{
+        .root_source_file = b.path("src/test/harness.zig"),
         .target = target,
         .optimize = optimize,
         .link_libc = true,
-    }));
-    const e2e = b.addExecutable(.{ .name = "e2e-ios", .root_module = e2e_mod });
-    const run_e2e = b.addRunArtifact(e2e);
-    run_e2e.addArtifactArg(exe);
-    run_e2e.addPassthruArgs();
-    const e2e_step = b.step("e2e-ios", "Run iOS end-to-end tests (needs a booted simulator)");
-    e2e_step.dependOn(&run_e2e.step);
+    });
+    harness_mod.addImport("io", io_mod);
+
+    const Suite = struct { step: []const u8, src: []const u8, desc: []const u8 };
+    const suites = [_]Suite{
+        .{
+            .step = "e2e-ios",
+            .src = "src/test/e2e_ios.zig",
+            .desc = "Run iOS end-to-end tests (simulator; skips what the host cannot provide)",
+        },
+        .{
+            .step = "e2e-ios-device",
+            .src = "src/test/e2e_ios_device.zig",
+            .desc = "Run iOS end-to-end tests against an attached physical device",
+        },
+    };
+    for (suites) |s| {
+        const mod = b.createModule(.{
+            .root_source_file = b.path(s.src),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        });
+        mod.addImport("io", io_mod);
+        mod.addImport("harness", harness_mod);
+        const exe_suite = b.addExecutable(.{ .name = s.step, .root_module = mod });
+        const run_suite = b.addRunArtifact(exe_suite);
+        run_suite.addArtifactArg(exe);
+        run_suite.addPassthruArgs();
+        b.step(s.step, s.desc).dependOn(&run_suite.step);
+
+        // The suites' own parsing helpers — which udid a listing names, which
+        // pid a launch printed — decide what the hardware cases assert on, so
+        // they belong in `zig build test` where they run everywhere. Needs a
+        // second module: a test root cannot be shared with an executable root.
+        const test_suite_mod = b.createModule(.{
+            .root_source_file = b.path(s.src),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        });
+        test_suite_mod.addImport("io", io_mod);
+        test_suite_mod.addImport("harness", harness_mod);
+        test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = test_suite_mod })).step);
+    }
 }

kuri-mobile/build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .kuri_mobile,
-    .version = "0.4.10",
+    .version = "0.4.11",
     .dependencies = .{},
     .fingerprint = 0x41cfa5929f72d020,
     .minimum_zig_version = "0.17.0-dev.813+2153f8143",

kuri-mobile/src/common/io.zig

@@ -176,6 +176,43 @@ pub fn sleepMs(ms: u64) void {
     _ = std.c.nanosleep(&ts, null);
 }
 
+/// Read a whole file into an allocated slice. Caller frees.
+///
+/// Needed because `devicectl` never writes JSON to stdout — its only
+/// machine-readable channel is `--json-output <path>`, so reading it back off
+/// disk is the entire structured-output path for real devices.
+pub fn readFile(allocator: std.mem.Allocator, path: []const u8, max_bytes: usize) ![]u8 {
+    var pbuf: [4096]u8 = undefined;
+    if (path.len >= pbuf.len) return error.NameTooLong;
+    @memcpy(pbuf[0..path.len], path);
+    pbuf[path.len] = 0;
+    const fd = std.c.open(pbuf[0..path.len :0], .{ .ACCMODE = .RDONLY }, @as(std.c.mode_t, 0));
+    if (fd < 0) return error.OpenFailed;
+    defer _ = std.c.close(fd);
+
+    var out: std.ArrayList(u8) = .empty;
+    errdefer out.deinit(allocator);
+    var buf: [4096]u8 = undefined;
+    while (true) {
+        const n = std.c.read(fd, &buf, buf.len);
+        if (n < 0) return error.ReadFailed;
+        if (n == 0) break;
+        const bytes: usize = @intCast(n);
+        if (out.items.len + bytes > max_bytes) return error.FileTooLarge;
+        try out.appendSlice(allocator, buf[0..bytes]);
+    }
+    return out.toOwnedSlice(allocator);
+}
+
+/// Best-effort unlink, for scratch files whose removal is not worth an error.
+pub fn removeFile(path: []const u8) void {
+    var pbuf: [4096]u8 = undefined;
+    if (path.len >= pbuf.len) return;
+    @memcpy(pbuf[0..path.len], path);
+    pbuf[path.len] = 0;
+    _ = std.c.unlink(pbuf[0..path.len :0]);
+}
+
 /// Write bytes to a file path (overwriting). Uses libc to avoid std.fs.File.
 pub fn writeFile(path: []const u8, data: []const u8) !void {
     var pbuf: [4096]u8 = undefined;

kuri-mobile/src/doctor.zig

@@ -83,8 +83,18 @@ pub fn run(gpa: std.mem.Allocator) !u8 {
         // --- Simulator.app --------------------------------------------------
         if (sim_ax.simulatorPid(gpa)) |maybe_pid| {
             if (maybe_pid) |pid| {
-                const d = try std.fmt.allocPrint(rep.arena, "running (pid {d})", .{pid});
-                rep.line(.ok, "Simulator.app", d);
+                // Running is not sufficient: the accessibility tree hangs off a
+                // window, and `simctl boot` does not open one. Reporting only
+                // the process made a windowless Simulator look healthy right up
+                // until uitree failed.
+                if (sim_ax.hasOpenWindow(gpa)) {
+                    const d = try std.fmt.allocPrint(rep.arena, "running (pid {d}), window on screen", .{pid});
+                    rep.line(.ok, "Simulator.app", d);
+                } else {
+                    const d = try std.fmt.allocPrint(rep.arena, "running (pid {d}) but no window — uitree/find/wait-for-ui need one", .{pid});
+                    rep.line(.warn, "Simulator.app", d);
+                    rep.hint("kuri-mobile ios open-sim");
+                }
             } else {
                 rep.line(.warn, "Simulator.app", "not running — input and uitree need it open");
                 rep.hint("kuri-mobile ios open-sim");