simframe 0.14.3 → 0.15.1

package/README.md

@@ -323,6 +323,7 @@ boundary hands it frames and nothing above it knows what a simulator is.
 | Clipboard, and `paste` into a field | yes | the emulator's gRPC `setClipboard`, over `node:http2`, no dependency, then `KEYCODE_PASTE` to deliver it |
 | List/resolve devices, launch, terminate, open a URL, permissions | yes | `adb`, with the permission state read back off the device |
 | Accessibility tree | **not available (OCR + CV only)** | `uiautomator dump` costs **2,012 ms** a read, against 45 ms for the iOS tree. See [`docs/DEFERRED.md`](docs/DEFERRED.md) |
+| A launch confirmed to have reached the front | **not available (the launch is not checked)** | iOS compares the pid `simctl launch` printed against the pid the device reports as frontmost, in **2–5 ms**. Nothing here reports either; `am start` fronts synchronously, which is why it has not bitten — but that is not a check. See [`docs/DEFERRED.md`](docs/DEFERRED.md) |
 
 ```bash
 # an emulator is found the same way a simulator is
@@ -402,7 +403,7 @@ steer the model is a tool surface the model uses wrong.
 | `sim_flow_run` | Replay a flow that verified end to end. |
 | `sim_find` | Resolve an intent to one control, without acting on it. |
 | `sim_tap` · `sim_type_into` · `sim_scroll_to` · `sim_wait_for` · `sim_assert` | Single actions, for when you genuinely only have one step. Each is one `sim_do` step underneath. |
-| `sim_launch` · `sim_open_url` · `sim_permission` | Launch with arguments and environment; open a deep link; grant a privacy permission instead of tapping a system alert. |
+| `sim_launch` · `sim_open_url` · `sim_permission` | Launch with arguments and environment; open a deep link; grant a privacy permission instead of tapping a system alert. A launch is **confirmed to have reached the front**, by comparing the pid `simctl` started against the pid the device reports as frontmost — so *"the process started"* is no longer reported as *"the app is on screen"*. |
 | `sim_wait` | Waits for the screen to change *and then* settle. |
 | `sim_look` | **The only tool that returns an image**, capped at 1024 px. For layout, colour, spacing — questions text cannot answer. |
 | `sim_recall` · `sim_strip` | Look backwards: a text timeline of what happened, or recent frames tiled into one image. |
@@ -994,11 +995,22 @@ said a word — the exact failure shape, found by the thing built to catch it.
   dramatically between visits will simply be rebuilt.
 - It speeds up *confirming* a fix, not *locating* one. A bug living in a memo
   comparator or a stale closure is not visible in any frame.
-- A switch is tapped at the centre of its frame, and a switch's frame is the
-  whole row — so the tap lands on the label and the control, which sits at the
-  trailing end, does not move. Use `@x,y` on the control for now. Filed with
-  the measurement in `docs/DEFERRED.md`; it is a role-specific tap point, not a
-  patch at one call site.
+- A switch is tapped at its **activation point** when the app publishes one —
+  UIKit's `accessibilityActivationPoint`, which is what a switch answers with,
+  and tapping it flipped a real switch 3 of 3 times where the frame centre
+  managed 0 of 3. Only **4 of 75** elements on a measured screen publish one,
+  though, so where the app says nothing the tap still goes to the centre of the
+  frame — and a switch's frame is the whole row, so it lands on the label and
+  the control at the trailing end does not move. `@x,y` remains the escape
+  hatch there. Never a guessed offset: nil means the app did not answer.
+- A launch is confirmed to have fronted **on iOS only**. It compares the pid
+  `simctl launch` printed against the pid the device reports as frontmost, in
+  2–5 ms. Android reports neither, so a launch there is not checked — `am start`
+  fronts synchronously, which is why it has not bitten, but that is not a check
+  and `doctor` says so. Note that a launch which starts a process without
+  bringing it forward now **fails** rather than returning success: a flow that
+  used to pass through such a launch and then assert on the previous app's
+  screen will start failing, correctly.
 - The simulator's display pipeline stops rendering under rapid app relaunch —
   about six cycles, reproducibly — and every frame comes back black while
   `simctl` itself reports success. simframe now says so instead of reading a

package/native/simframed/Sources/PrivateAPI/AccessibilityBridge.swift

@@ -62,6 +62,24 @@ public struct AXTree: Sendable {
     }
 }
 
+/// The application the device is showing right now.
+///
+/// Deliberately not a bundle id: nothing on this path publishes one, and a
+/// display name that merely *looks* like an identifier would invite exactly the
+/// string comparison this type exists to avoid.
+public struct FrontmostApp: Sendable {
+    /// The guest pid, or nil when the frontmost application object would not
+    /// answer for it. Nil is "cannot say", never "not that app".
+    public let pid: Int32?
+    /// The application element's own title, for reporting.
+    public let title: String?
+
+    public init(pid: Int32?, title: String?) {
+        self.pid = pid
+        self.title = title
+    }
+}
+
 public enum AccessibilityError: Error, CustomStringConvertible {
     case unavailable(String)
     case noFrontmostApplication
@@ -219,11 +237,54 @@ public final class AccessibilityBridge {
         }
     }
 
-    /// The pid of the app currently frontmost, or nil when the bridge cannot say.
-    public func frontmostPid() -> Int32? {
-        guard let app = frontmostApplication() else { return nil }
-        guard app.responds(to: NSSelectorFromString("pid")) else { return nil }
-        return (app.value(forKey: "pid") as? NSNumber)?.int32Value
+    /// Who is in front, as the device itself reports it.
+    ///
+    /// This exists because `launch` could not tell "the app was already in
+    /// front" from "the app never came forward": both return ok and both leave
+    /// the screen unchanged. Screen change cannot settle it either way —
+    /// relaunching an app that is already frontmost legitimately lands on the
+    /// same screen — so the discriminator has to be identity.
+    ///
+    /// `pid` is the number to compare against, because it is the same one
+    /// `simctl launch` prints, so the caller tests equality rather than
+    /// matching a display name against a bundle id. `title` is for the human
+    /// reading the verdict and is a display name, not an identifier.
+    public func frontmostApp() throws -> FrontmostApp {
+        guard let app = frontmostApplication() else { throw AccessibilityError.noFrontmostApplication }
+        let pid = app.responds(to: NSSelectorFromString("pid"))
+            ? (app.value(forKey: "pid") as? NSNumber)?.int32Value
+            : nil
+        // Probing several names rather than trusting one, because a bare pid is
+        // not a diagnosis. A runner held the front at pid 7797 through nine
+        // consecutive failed launches and the whole question was whether that
+        // was SpringBoard or a lock screen — unanswerable from a number.
+        var title: String?
+        if let root = elementClass
+            .perform(NSSelectorFromString("platformElementWithTranslationObject:"), with: app)?
+            .takeUnretainedValue() as? NSObject {
+            // Reported RAW, generic answers included, and the judgement about
+            // them is made a layer up. Measured: in Settings this reads
+            // "Settings"; press home and the SAME pid is still frontmost while
+            // the answer degrades to the bare word "application". That
+            // degradation is a signal — an app frontmost by pid that has
+            // stopped naming itself is the shape item 171 is about — so
+            // swallowing it here would throw away the interesting half. This
+            // file's job is to say what the translator said.
+            for name in ["AXTitle", "AXDescription"] {
+                if let found = string(attribute(root, name)) { title = found; break }
+            }
+        }
+        // The translation object itself, if the element would not say. Keys, not
+        // selectors, because these are properties on a private class and a key
+        // that is absent is caught by `responds(to:)` rather than by an
+        // Objective-C exception Swift cannot catch.
+        if title == nil {
+            for key in ["bundleId", "bundleIdentifier", "displayName", "processName"]
+            where app.responds(to: NSSelectorFromString(key)) {
+                if let found = string(app.value(forKey: key)) { title = found; break }
+            }
+        }
+        return FrontmostApp(pid: pid, title: title)
     }
 
     private func frontmostApplication() -> NSObject? {

package/native/simframed/Sources/PrivateAPI/CoreSimulatorPlatform.swift

@@ -275,6 +275,10 @@ public final class CoreSimulatorPlatform: SimulatorPlatform {
         try bridge().tree()
     }
 
+    public func frontmostApp() throws -> FrontmostApp {
+        try bridge().frontmostApp()
+    }
+
     /// Serialised, because building a bridge installs a delegate on a
     /// **process-global** translator that holds it weakly.
     ///

package/native/simframed/Sources/PrivateAPI/PrivateAPI.swift

@@ -171,6 +171,13 @@ public protocol SimulatorPlatform: AnyObject {
     /// An app still launching has no tree yet, and this reports that as it is —
     /// one node, no children — rather than retrying until it looks populated.
     func accessibilityTree() throws -> AXTree
+    /// Which application the device is showing, when the platform can say.
+    ///
+    /// Separate from `accessibilityTree()` even though the same bridge answers
+    /// both, because the caller that needs it — "did the app I launched come
+    /// forward?" — must not pay for a whole tree walk to ask a one-field
+    /// question, and must be able to ask it repeatedly while waiting.
+    func frontmostApp() throws -> FrontmostApp
 
     // MARK: App lifecycle. These are simctl, not private API — no HID needed.
 

package/native/simframed/Sources/PrivateAPI/StubPlatform.swift

@@ -14,6 +14,8 @@ public final class StubPlatform: SimulatorPlatform {
     /// What `accessibilityTree()` should answer. Empty by default, which is
     /// what a device with no app in the foreground genuinely looks like.
     public var stubTree: AXTree = AXTree(nodes: [])
+    /// What `frontmostApp()` should answer.
+    public var stubFrontmost = FrontmostApp(pid: 1234, title: "Stub")
 
     public init(width: Int = 1206, height: Int = 2622, tint: UInt8 = 0) {
         self.width = width
@@ -130,4 +132,9 @@ extension StubPlatform {
         recorded.append("accessibilityTree()")
         return stubTree
     }
+
+    public func frontmostApp() throws -> FrontmostApp {
+        recorded.append("frontmostApp()")
+        return stubFrontmost
+    }
 }

package/native/simframed/Sources/simframed/main.swift

@@ -235,6 +235,16 @@ case "run":
                                    "scale": device.scale],
                         "engine": "simframed",
                     ])
+                case "frontmost":
+                    // The one-field question, on its own action, because the
+                    // caller asks it in a loop while waiting for a launch to
+                    // land. Routing it through "ui" would pay for a tree walk
+                    // and an OCR pass per poll.
+                    let front = try platform.frontmostApp()
+                    var out: [String: Any] = [:]
+                    if let pid = front.pid { out["pid"] = Int(pid) }
+                    if let title = front.title { out["title"] = title }
+                    return done(out)
                 case "ui":
                     // The accessibility tree and OCR read the same instant of
                     // the screen and neither needs the other, so they run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.14.3",
+  "version": "0.15.1",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator and Android emulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [

package/scripts/bench-hpi.mjs

@@ -186,11 +186,7 @@ const report = {
 
 console.log('\nflow                      runs  agent p50   human p50   HPI_time  step_ratio');
 for (const f of report.flows) {
-  console.log(
-    `${f.flow.padEnd(24)} ${String(f.runs).padStart(5)}  ${`${f.agent_ms.p50}ms`.padStart(9)}   ` +
-      `${(f.human_median_ms ? `${f.human_median_ms}ms` : '—').padStart(9)}   ` +
-      `${String(f.hpi_time ?? '—').padStart(8)}  ${String(f.step_ratio ?? '—').padStart(10)}`,
-  );
+  console.log(metrics.flowRow(f));
 }
 report.overall.hpi_time_median_of_passes = passTimes.length ? Number(metrics.median(passTimes).toFixed(3)) : null;
 const o = report.overall;

package/scripts/ci-device-guard.mjs

@@ -23,33 +23,8 @@
 // becomes visible instead of arguable.
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
+import { deviceCause } from './device-state.mjs';
 
-/** Conditions that are the simulator, not the code. Each seen in a real run. */
-const DEVICE_STATE = [
-  [/NSPOSIXErrorDomain.*code=?\s*60|Operation timed out/i, 'simctl stopped answering (NSPOSIXErrorDomain 60)'],
-  [/did not produce a frame|produced no frame in \d+s/i, 'the daemon is up and the display renders nothing'],
-  [/Timeout waiting for screen surfaces|display surface is not answering|display surface could not be read/i, 'the display surface is wedged'],
-  [/no frames buffered|capture is wedged/i, 'capture stopped'],
-  [/the second app never launched|could not be dispatched/i, 'an app would not launch'],
-  // A launched app that never comes to the front, seen as the tour waiting for
-  // one of its landmarks on a screen that is showing a clock and nothing else.
-  //
-  // Measured on a runner: `ok launch — launched com.apple.Preferences
-  // (relaunched)` followed by `waited 8000ms for General: "General" is not on
-  // this screen. Visible: 10:50, .?o (the screen has not moved for 6181ms)`.
-  // Two labels, one of them a clock, on a still screen — the device is not
-  // presenting the app, and the guard called that a check failing on its
-  // merits and declined to revive.
-  //
-  // Deliberately narrow. It requires the wait to have failed AND the screen to
-  // have been still AND almost nothing readable: a tour that genuinely asks for
-  // the wrong label has a screen full of other labels, and must keep failing
-  // rather than being retried into a pass.
-  [
-    /never arrived[\s\S]*?Visible:[^\n]{0,24}\(the screen has not moved for \d+ms/i,
-    'a launched app never came to the front (the screen shows a clock and nothing else)',
-  ],
-];
 
 const udid = process.argv[2];
 const sep = process.argv.indexOf('--');
@@ -74,8 +49,6 @@ const summary = (line) => {
   if (f) { try { fs.appendFileSync(f, `${line}\n`); } catch { /* summaries are a nicety */ } }
 };
 
-const deviceCause = (text) => DEVICE_STATE.find(([re]) => re.test(text))?.[1] ?? null;
-
 const first = await run(cmd);
 if (first.code === 0) process.exit(0);
 

package/scripts/device-state.mjs

@@ -0,0 +1,62 @@
+// Is a failed CI step the device's fault or the check's?
+//
+// Its own module, and the reason is the same one that moved `classifyStray` out
+// of `eval-fingerprint.mjs`: `ci-device-guard.mjs` reads `process.argv` and
+// `process.exit(2)`s at import, so nothing could ever test this table there —
+// and the only thing that exercised it was a hosted runner, at the end of a
+// fifteen-minute job, in the middle of a report. Two runtime bugs in this
+// project came from logic that was correct and had never executed.
+//
+// Every entry here has been seen in a real run. Adding one from imagination is
+// how a guard starts reviving genuine failures into passes.
+
+/** Conditions that are the simulator, not the code. Each seen in a real run. */
+export const DEVICE_STATE = [
+  [/NSPOSIXErrorDomain.*code=?\s*60|Operation timed out/i, 'simctl stopped answering (NSPOSIXErrorDomain 60)'],
+  [/did not produce a frame|produced no frame in \d+s/i, 'the daemon is up and the display renders nothing'],
+  [/Timeout waiting for screen surfaces|display surface is not answering|display surface could not be read/i, 'the display surface is wedged'],
+  [/no frames buffered|capture is wedged/i, 'capture stopped'],
+  [/the second app never launched|could not be dispatched/i, 'an app would not launch'],
+  // A launched app that never comes to the front, seen as the tour waiting for
+  // one of its landmarks on a screen that is showing a clock and nothing else.
+  //
+  // Measured on a runner: `ok launch — launched com.apple.Preferences
+  // (relaunched)` followed by `waited 8000ms for General: "General" is not on
+  // this screen. Visible: 10:50, .?o (the screen has not moved for 6181ms)`.
+  // Two labels, one of them a clock, on a still screen — the device is not
+  // presenting the app, and the guard called that a check failing on its
+  // merits and declined to revive.
+  //
+  // Deliberately narrow. It requires the wait to have failed AND the screen to
+  // have been still AND almost nothing readable: a tour that genuinely asks for
+  // the wrong label has a screen full of other labels, and must keep failing
+  // rather than being retried into a pass.
+  [
+    /never arrived[\s\S]*?Visible:[^\n]{0,24}\(the screen has not moved for \d+ms/i,
+    'a launched app never came to the front (the screen shows a clock and nothing else)',
+  ],
+  // The same condition, now said outright by the step that suffered it instead
+  // of inferred from the shape of the screen afterwards. Item 169 gave `launch`
+  // a pid to compare, so a launch that starts a process and never fronts it
+  // reports itself; this signature fires on the cause rather than on a
+  // consequence that had to be recognised by "two labels, one a clock".
+  //
+  // It cannot be triggered by a tour asking for the wrong label — only a failed
+  // launch emits this sentence — so it needs none of the narrowing above.
+  [
+    /never came to the front within \d+ms/i,
+    'a launched app never came to the front (the launch said so itself, by pid)',
+  ],
+  // Seen on the v0.14.3 bench run: `could not launch com.apple.Preferences:
+  // The system shell (SpringBoard:36454) probably crashed.` The guest's window
+  // server going down is the device, not the check, and nothing here matched it.
+  [
+    /system shell \(SpringBoard[^)]*\) probably crashed/i,
+    "the guest's SpringBoard crashed, so nothing can be fronted",
+  ],
+];
+
+/** The condition this output shows, or null when the check failed on its merits. */
+export function deviceCause(text) {
+  return DEVICE_STATE.find(([re]) => re.test(String(text ?? '')))?.[1] ?? null;
+}

package/src/actions.js

@@ -3,6 +3,7 @@
 // Waiting uses a baseline captured BEFORE each action, which is the whole
 // reason these scripts are reliable rather than racy.
 import * as api from './index.js';
+import * as frontmost from './frontmost.js';
 import * as graph from './graph.js';
 import * as input from './input.js';
 import * as intent from './intent.js';
@@ -396,12 +397,15 @@ export async function runScript(
       // its coordinates from the screen size. Reading them back off the step
       // would diagnose a point nothing was ever aimed at.
       const aim = { at: null };
+      // Carried out of the dispatch the way `aim` is, because the note that
+      // reads it is built after the step has returned a string.
+      const landing = { verdict: null };
       let detail;
       // A selector that did not resolve gets the step's own alternatives before
       // the batch is abandoned. Anything else propagates: retrying from a screen
       // we did not expect to be on is not a retry, it is a second guess.
       try {
-        detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus, aim });
+        detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus, aim, landing });
       } catch (thrown) {
         let err = thrown;
         // Ask the supervisor before anything is abandoned. It sits behind the
@@ -435,7 +439,7 @@ export async function runScript(
             options,
           }).catch(() => null);
           try {
-            detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus, aim });
+            detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus, aim, landing });
             detail += ` [the local supervisor said ${ruling.decision}; it worked on the second attempt]`;
             ruled('recovered');
             continue;
@@ -475,7 +479,7 @@ export async function runScript(
         let last = err;
         for (const label of allowed) {
           try {
-            detail = await runStep(deviceQuery, udid, stepWithTarget(step, label), { screen, options, frames, focus, aim });
+            detail = await runStep(deviceQuery, udid, stepWithTarget(step, label), { screen, options, frames, focus, aim, landing });
             detail += ` [after ${tried.map((t) => JSON.stringify(String(t))).join(', ')} did not resolve]`;
             last = null;
             break;
@@ -770,8 +774,14 @@ export async function runScript(
       // front an already-running app, so the first reading is the likely one —
       // but likely is not the same as said, and the step is the only place that
       // can say it.
+      // Item 169 closed the ambiguity this comment describes, so the note no
+      // longer has to hedge when the pid answered. `fronted` with an unmoved
+      // screen is now a *fact* about which reading was right, not a guess:
+      // the app is confirmed in front, so it was already there.
       const launchNote = step.action === 'launch' && settled?.noVisibleChange
-        ? ' [the screen did not change, so this app was already in front — or it did not come forward]'
+        ? (landing.verdict === 'fronted'
+          ? ' [the screen did not change and this app is confirmed frontmost — it was already in front]'
+          : ' [the screen did not change, so this app was already in front — or it did not come forward]')
         : '';
       const filling = stillFillingIn(afterReading?.entry);
       // Item 120: when a gesture aimed at a coordinate does nothing, say what
@@ -2483,12 +2493,54 @@ async function runStep(deviceQuery, udid, step, ctx) {
       return `pressed key ${step.value ?? step.code}`;
     case 'launch': {
       const bundleId = step.value ?? step.bundleId;
-      await launchApp(udid, bundleId, {
+      const started = await launchApp(udid, bundleId, {
         args: step.args ?? [],
         env: step.env ?? {},
         terminateFirst: step.relaunch === true,
       });
-      return `launched ${bundleId}${step.relaunch ? ' (relaunched)' : ''}`;
+      // Item 169: simctl returning ok means the process started, not that the
+      // app came forward, and the two came apart repeatedly on a loaded
+      // runner — leaving the device on the previous app under a step that
+      // reported success. The pid settles it; the screen cannot.
+      let landed = await frontmost.check(udid, started?.pid ?? null);
+      // One bounded retry, on a condition we have now *measured* rather than
+      // guessed at. This was rejected in the first pass for a good reason —
+      // retrying on "no visible change" papers over a signal that cannot tell
+      // success from failure — and that objection does not apply to a known
+      // `did-not-front`: the app is running, a second `launch` without a
+      // terminate simply fronts it, and that is the 237ms path.
+      //
+      // It is deliberately NOT a terminate-and-relaunch. That is the gesture
+      // this project already knows wedges the simulator's display pipeline
+      // (README, "rapid app relaunch"), so the recovery must not be the thing
+      // that causes the next failure.
+      //
+      // Reported, never silent: CI's own step vehicle has been doing this by
+      // hand three times, invisibly, which is how the defect stayed at the
+      // harness layer for so long. A retry that does not show up in the
+      // summary is a rate nobody can argue with.
+      let retried = null;
+      if (landed.verdict === 'did-not-front') {
+        retried = landed;
+        await launchApp(udid, bundleId, { args: step.args ?? [], env: step.env ?? {} });
+        landed = await frontmost.check(udid, started?.pid ?? null);
+      }
+      if (landed.verdict === 'did-not-front') {
+        throw new Error(
+          `launched ${bundleId} (pid ${started.pid}) but it never came to the front`
+          + ` within ${landed.ms}ms${retried ? ', on either of two attempts' : ''} — ${landed.frontmost === null
+            ? 'nothing is frontmost'
+            : `${landed.holder} still is`}`
+          + `. ${frontmost.describeHeld(landed.held, started.pid)}.`,
+        );
+      }
+      if (ctx.landing) ctx.landing.verdict = landed.verdict;
+      return `launched ${bundleId}${step.relaunch ? ' (relaunched)' : ''}`
+        + (landed.verdict === 'fronted' ? ` (frontmost after ${landed.ms}ms)` : '')
+        + (retried
+          ? ` [it did not front on the first attempt — ${frontmost.describeHeld(retried.held, started.pid)}`
+            + `; a second launch fronted it. The launch is unreliable on this host.]`
+          : '');
     }
     case 'terminate':
       await terminateApp(udid, step.value ?? step.bundleId);

package/src/baseline.js

@@ -175,7 +175,22 @@ export async function resetFor(udid, flow) {
       for (let attempt = 0; attempt <= (reset.maxBack ?? 4); attempt += 1) {
         await api.waitFor(udid, { mode: 'stable', stableMs: 350, timeoutMs: 3000 });
         try {
-          await api.locate(udid, reset.rootMarker, { refresh: attempt > 0 });
+          // **Fresh on every attempt, the first one included.** This read
+          // `refresh: attempt > 0`, which is the exact pattern `actions.js`
+          // has a test forbidding — and the test only ever read actions.js, so
+          // the same defect sat here unguarded. It is not theoretical: the
+          // reset ran immediately after a launch, resolved `Accessibility`
+          // against the map remembered from the PREVIOUS run's end screen,
+          // did not find it, and went looking for a "back" control on a
+          // Settings root that has none:
+          //
+          //   (reset: could not return com.apple.Preferences to its root
+          //    screen: "back" is not on this screen. Visible: Settings,
+          //    Apple Account, …, Accessibility, …)
+          //
+          // Accessibility is right there in that list. A check has no second
+          // opinion, so it may not resolve its first look from memory.
+          await api.locate(udid, reset.rootMarker, { refresh: true });
           break;
         } catch {
           const back = await api.locate(udid, 'back', { refresh: true });

package/src/cli.js

@@ -1234,11 +1234,7 @@ async function main() {
       emit(flags, report, [
         flags.last ? `the last ${num(flags.last)} run(s) of each flow, of ${all.filter((f) => f.flow_name).length} named runs in the log` : null,
         'flow                      runs  agent p50   human p50   HPI_time  step_ratio  turns  esc',
-        ...report.flows.map((f) =>
-          `${f.flow.padEnd(24)} ${String(f.runs).padStart(5)}  ${`${f.agent_ms.p50}ms`.padStart(9)}   ` +
-          `${(f.human_median_ms ? `${f.human_median_ms}ms` : '—').padStart(9)}   ` +
-          `${(f.hpi_time ?? '—').toString().padStart(8)}  ${(f.step_ratio ?? '—').toString().padStart(10)}  ` +
-          `${(f.model_turns ?? '—').toString().padStart(5)}  ${String(f.escalations).padStart(3)}`),
+        ...report.flows.map((f) => metrics.flowRow(f, { wide: true })),
         '',
         `HPI_accuracy ${report.overall.hpi_accuracy} (${report.overall.runs} runs, ` +
           `${report.overall.runs - runs.filter((r) => r.completed && !r.wrong_action_taken).length} not clean)`,
@@ -1704,6 +1700,15 @@ async function doctor({ json = false, strict = false, device, options = {} } = {
       }
       add(`text recognition (${d.name})`, 'ok',
         daemon ? 'simframed (in-process, off the framebuffer)' : 'sips + helper binary');
+      // Before the `ax` early-out, so a backend without a tree still reports
+      // this one: "is a launch checked?" is a question the user needs answered
+      // on every platform, and item 169 is what an unanswered launch cost.
+      const front = caps.frontmost ?? { supported: false, note: 'this backend does not say' };
+      add(`launch verification (${d.name})`, front.supported ? 'ok' : 'optional',
+        front.supported
+          ? `${front.via} — a launch that never fronts is reported, not called success`
+          : front.note,
+        { key: 'launch.frontmost', value: front.supported ? front.via ?? 'yes' : null });
       if (!caps.ax.supported) {
         add(`accessibility tree (${d.name})`, 'optional', caps.ax.note, { key: 'ax.driver', value: null });
         continue;

package/src/control.js

@@ -72,6 +72,8 @@ export const longPress = (udid, x, y, opts = {}) => request(udid, { action: 'lon
 export const drag = (udid, from, to, opts = {}) =>
   request(udid, { action: 'drag', x1: from.x, y1: from.y, x2: to.x, y2: to.y, ...opts });
 export const launch = (udid, bundleId, opts = {}) => request(udid, { action: 'launch', bundleId, ...opts });
+/** Which app the device is showing, by pid — see src/frontmost.js. */
+export const frontmost = (udid) => request(udid, { action: 'frontmost' });
 export const terminate = (udid, bundleId) => request(udid, { action: 'terminate', bundleId });
 export const openUrl = (udid, url) => request(udid, { action: 'openUrl', url });
 export const permission = (udid, permissionAction, service, bundleId) =>

package/src/frontmost.js

@@ -0,0 +1,171 @@
+// Did the app we launched actually come forward?
+//
+// `launch` could not answer that, and item 169 is what it cost: `launch
+// com.apple.Preferences (relaunch: true)` returning ok, reporting `[no visible
+// change]`, with the device still on the previous app. The CI workflow's own
+// step vehicle retries `simctl launch` three times by hand for exactly this, so
+// the failure was known at the harness layer and unhandled at the library
+// layer, where every user meets it.
+//
+// **Screen change cannot settle it, and that dead end was checked first.**
+// Relaunching an app that is already frontmost legitimately lands on the same
+// screen, so "no visible change" is shared by the success and the failure. The
+// discriminator has to be identity.
+//
+// The identity is a **pid**, not a name, and that is the whole reason this works
+// cheaply: `simctl launch` prints the pid it started, and the daemon's
+// `frontmost` action reports the pid of the application AXPTranslator says is in
+// front. Measured on a real device — 10695/10695 for Preferences,
+// 10762/10762 for Contacts — so the caller compares two integers instead of
+// matching a display name against a bundle id.
+//
+// Its own module, with the device read injectable, because the only thing that
+// ever exercises a launch is a device: a unit test replays pid sequences
+// through `landed` and never boots anything.
+import * as control from './control.js';
+
+/**
+ * How long to wait for the app to reach the front.
+ *
+ * Measured, not chosen for feel: an already-running app fronts in ~240 ms and a
+ * cold switch to Contacts took 1552 ms on this machine. 5 s leaves room for a
+ * loaded runner — the same host where `simctl launch` itself has measured
+ * 47–55 s — while still being far below the point where a caller gives up.
+ */
+export const FRONT_BUDGET_MS = 5000;
+export const POLL_MS = 100;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Words the translator hands back when it has no name to give.
+ *
+ * Measured on a device: the application element's title is "Settings" while
+ * Settings is on screen, and after a press of home the **same pid** is still
+ * frontmost with the title degraded to the bare word "application". That is
+ * not a name, and printing it as one would be a confident wrong answer in
+ * precisely the state worth noticing — an app frontmost by pid that has
+ * stopped naming itself. So the word is kept (the daemon reports raw) and
+ * phrased honestly here, where it can be tested without a device.
+ */
+const GENERIC_NAMES = new Set(['application', 'window', 'unknown', 'group', 'element']);
+
+/** How to refer to whoever holds the front. */
+export function nameHolder(pid, title) {
+  if (pid === null || pid === undefined) return 'nothing';
+  // Blank counts as absent, not as a degraded answer: whitespace is the
+  // translator saying nothing, and "no longer names itself" is a claim about
+  // an app that answered.
+  const said = typeof title === 'string' ? title.trim() : '';
+  if (!said) return `pid ${pid}`;
+  return GENERIC_NAMES.has(said.toLowerCase())
+    ? `pid ${pid} (an app that no longer names itself)`
+    : `pid ${pid} (${said})`;
+}
+
+/** Who is on screen — pid to compare, title to report. Nulls mean "cannot say". */
+export async function read(udid) {
+  if (!udid || !control.available(udid)) return { pid: null, title: null };
+  try {
+    const r = await control.request(udid, { action: 'frontmost' });
+    return { pid: typeof r?.pid === 'number' ? r.pid : null, title: r?.title ?? null };
+  } catch {
+    // A daemon that cannot answer is "cannot say". Reporting it as "not that
+    // app" would turn a missing sensor into a failed launch, which is the
+    // false refusal item 161 was reverted for.
+    return { pid: null, title: null };
+  }
+}
+
+/** The pid alone, for callers that only compare. */
+export const frontmostPid = async (udid) => (await read(udid)).pid;
+
+/**
+ * Wait for `pid` to be the app in front.
+ *
+ * Three verdicts, and the third is not a failure:
+ *
+ * - `fronted` — the launched pid is the frontmost pid. The launch worked,
+ *   whether or not the screen moved.
+ * - `did-not-front` — the budget expired with someone else in front. This is
+ *   the defect, now visible.
+ * - `cannot-say` — no pid from the launch, or nothing on this platform reports
+ *   who is frontmost. The caller keeps whatever it said before this existed.
+ *
+ * @param {object} o
+ * @param {number|null} o.pid   what the launch reported
+ * @param {() => Promise<{pid: number|null, title: string|null}>} o.read who is in front now
+ */
+export async function landed({
+  pid, read, budgetMs = FRONT_BUDGET_MS, pollMs = POLL_MS,
+  now = () => Date.now(), wait = sleep,
+} = {}) {
+  if (typeof pid !== 'number') {
+    return { verdict: 'cannot-say', reason: 'the launch did not report a pid' };
+  }
+  const started = now();
+  let seen = null;
+  let asked = 0;
+  // Who held the front while we waited, in order. The instrument, not decoration:
+  // "the budget was too short" and "the app never went anywhere" produce the same
+  // verdict and want opposite remedies, and one list of pids tells them apart —
+  // a front that changed hands twice is a slow device, a single pid for the whole
+  // budget is a launch that did not happen. Widening a budget without this is the
+  // mistake item 146 was, twice.
+  const held = [];
+  let holder = null;
+  for (;;) {
+    const look = await read();
+    seen = look?.pid ?? null;
+    asked += 1;
+    if (held[held.length - 1] !== seen) held.push(seen);
+    if (seen !== null) holder = look;
+    if (seen === pid) return { verdict: 'fronted', ms: now() - started, polls: asked, held };
+    // Checked after at least one read, so a platform that cannot answer says so
+    // rather than spending the whole budget finding that out.
+    if (seen === null && asked === 1) {
+      return { verdict: 'cannot-say', reason: 'nothing on this device reports which app is frontmost' };
+    }
+    if (now() - started >= budgetMs) {
+      return {
+        verdict: 'did-not-front',
+        ms: now() - started,
+        polls: asked,
+        frontmost: seen,
+        held,
+        // Named, not just numbered. A runner held the front at pid 7797 through
+        // nine consecutive failed launches and the only question that mattered
+        // — *what* is 7797 — was the one a number could not answer.
+        holder: nameHolder(seen, holder?.pid === seen ? holder.title : null),
+      };
+    }
+    await wait(pollMs);
+  }
+}
+
+/**
+ * `held` as a sentence, because a list of pids is not a diagnosis by itself.
+ *
+ * **Only meaningful for a `did-not-front`.** Handed a successful wait's `held`
+ * it says the launch never took effect about a launch that plainly did — I did
+ * exactly that while testing this — so `pid` is taken and the success is
+ * refused rather than described. Callers that hold the verdict gate on it;
+ * this is the belt for the one that forgets.
+ */
+export function describeHeld(held = [], pid = null) {
+  const real = held.filter((p) => p !== null);
+  if (pid !== null && real[real.length - 1] === pid) {
+    return `pid ${pid} did reach the front — there is nothing to explain`;
+  }
+  if (real.length <= 1) {
+    return real.length === 1
+      ? `pid ${real[0]} held the front for the whole wait, so the launch never took effect`
+      : 'nothing held the front at any point';
+  }
+  return `the front changed hands ${real.length - 1} time(s) (${real.join(' → ')}),`
+    + ' so the device was switching apps and simply never reached this one';
+}
+
+/** `landed`, reading from the daemon. */
+export const check = (udid, pid, opts = {}) =>
+  landed({ pid, read: () => read(udid), ...opts });

package/src/metrics.js

@@ -601,6 +601,30 @@ export function harmonicMean(xs) {
  * a human baseline. A flow with no human baseline gets no HPI_time — reported
  * as null, never as 1.0, because a missing denominator is not parity.
  */
+/**
+ * One flow's row in the HPI table, shared by `simframe hpi` and the bench
+ * script because they had the same row duplicated byte for byte.
+ *
+ * It lives here, next to the report it renders, for a reason the v0.15.0 tag
+ * paid for: making `agent_ms` null for a flow that timed nothing was correct,
+ * and both printers dereferenced `.p50` on it. `bench` died with exit 1 and no
+ * hpi.json, and `simframe hpi` would have done the same for any user whose
+ * flow never completed. The metric had a test; nothing rendered it. A format
+ * duplicated in two files is a format that gets fixed in one.
+ *
+ * `—` means "not measured", never zero.
+ */
+export function flowRow(f, { wide = false } = {}) {
+  const cell = (v, unit = '') => (v === null || v === undefined ? '—' : `${v}${unit}`);
+  const row = `${f.flow.padEnd(24)} ${String(f.runs).padStart(5)}  `
+    + `${cell(f.agent_ms?.p50, 'ms').padStart(9)}   `
+    + `${cell(f.human_median_ms, 'ms').padStart(9)}   `
+    + `${cell(f.hpi_time).padStart(8)}  ${cell(f.step_ratio).padStart(10)}`;
+  return wide
+    ? `${row}  ${cell(f.model_turns).padStart(5)}  ${String(f.escalations).padStart(3)}`
+    : row;
+}
+
 export function hpi({ flows, baselines = {} }) {
   const byName = new Map();
   for (const f of flows) {
@@ -610,13 +634,31 @@ export function hpi({ flows, baselines = {} }) {
   }
 
   const perFlow = [...byName.entries()].map(([name, runs]) => {
-    const agent = quartiles(runs.map((r) => r.wall_time_ms));
+    // **Time is measured over runs that finished the flow.** This took every
+    // run's wall time, failures included, and a failure is fast — so a change
+    // that broke a flow registered as the agent getting quicker.
+    //
+    // Measured, not hypothesised: `settings-larger-text` failed all three runs
+    // at ~3.6 s against a 7799 ms human median and reported `hpi_time 2.163`,
+    // i.e. "twice as fast as a person", about a flow that never once reached
+    // its destination. The composite `hpi` survives that because accuracy
+    // divides it down — but the CI gate's threshold is written against
+    // `HPI_time`, so the one number the gate reads was the one being flattered
+    // by breakage.
+    //
+    // A flow where nothing completed reports no time at all rather than a
+    // flattering one. That is the same discipline as the suite's own "no
+    // comparable HPI was measured": a number that cannot be compared must not
+    // be offered as one.
+    const finished = runs.filter((r) => r.completed);
+    const agent = quartiles(finished.map((r) => r.wall_time_ms));
     const human = baselines[name]?.wall_time_ms ?? null;
     const humanMedian = human?.p50 ?? null;
     const stepRatios = runs.map((r) => r.step_ratio).filter((x) => Number.isFinite(x));
     return {
       flow: name,
       runs: runs.length,
+      timed_runs: finished.length,
       agent_ms: agent,
       human_median_ms: humanMedian,
       hpi_time: humanMedian && agent?.p50 ? Number((humanMedian / agent.p50).toFixed(3)) : null,

package/src/platform/android.js

@@ -993,6 +993,16 @@ function capabilities() {
       supported: false,
       note: 'not built for Android yet — `uiautomator dump` costs ~2s a read; see docs/DEFERRED.md',
     },
+    // Not borrowed from iOS, and not claimed. iOS reads the frontmost pid off
+    // AXPTranslator and compares it with the pid `simctl launch` printed;
+    // neither half exists here — the emulator console launches by intent and
+    // reports no pid. `am start` does front the activity synchronously, which
+    // is why this has not been the same problem, but "has not been" is not a
+    // check and must not report as one.
+    frontmost: {
+      supported: false,
+      note: 'no frontmost-app read on Android yet, so a launch is not confirmed to have fronted; `am start` fronts synchronously, which is why this has not bitten — see docs/DEFERRED.md',
+    },
   };
 }
 

package/src/platform/ios.js

@@ -264,6 +264,13 @@ async function screenshot(udid, outFile, { mask = 'ignored' } = {}) {
  * simctl passes launch arguments after the bundle id and environment through
  * `SIMCTL_CHILD_`-prefixed variables of its own process — which is why env has
  * to be set on the child rather than passed as flags.
+ *
+ * Returns the pid simctl started, because starting an app and *fronting* an app
+ * are different events and only the pid connects them: the layer above compares
+ * it against the pid the device says is in front (item 169). simctl prints
+ * `com.apple.Preferences: 10695` and has always printed it; nobody had read it.
+ * A shape we do not recognise gives null, which reads as "cannot say" upstairs
+ * and never as a failed launch.
  */
 async function launchApp(udid, bundleId, { args = [], env = {}, terminateFirst = false } = {}) {
   if (terminateFirst) {
@@ -279,10 +286,11 @@ async function launchApp(udid, bundleId, { args = [], env = {}, terminateFirst =
   const childEnv = { ...process.env };
   for (const [k, v] of Object.entries(env)) childEnv[`SIMCTL_CHILD_${k}`] = String(v);
   try {
-    await run('xcrun', ['simctl', 'launch', udid, bundleId, ...args.map(String)], {
+    const { stdout } = await run('xcrun', ['simctl', 'launch', udid, bundleId, ...args.map(String)], {
       timeout: SIMCTL_TIMEOUT_MS,
       env: childEnv,
     });
+    return { pid: launchedPid(stdout) };
   } catch (err) {
     // execFile's message is just "Command failed: ..." with simctl's actual
     // complaint left in stderr. A CI run failed here and said nothing about
@@ -291,6 +299,12 @@ async function launchApp(udid, bundleId, { args = [], env = {}, terminateFirst =
   }
 }
 
+/** The pid out of simctl's `<bundle-id>: <pid>`, or null if it said otherwise. */
+export function launchedPid(stdout) {
+  const m = /:\s*(\d+)\s*$/.exec(String(stdout ?? '').trim());
+  return m ? Number(m[1]) : null;
+}
+
 async function terminateApp(udid, bundleId) {
   try {
     await run('xcrun', ['simctl', 'terminate', udid, bundleId], { timeout: SIMCTL_TIMEOUT_MS });
@@ -567,6 +581,11 @@ function capabilities() {
     captureEngines: ['simframed', 'screenshot'],
     input: { supported: true, via: 'daemon' },
     ax: { supported: true },
+    // Whether a launch can be confirmed to have reached the front. Declared
+    // separately from `ax` even though the same bridge answers both, because
+    // the user-visible consequence is different: without it `launch` reports
+    // that a process started and calls that success (item 169).
+    frontmost: { supported: true, via: 'AXPTranslator, compared by pid' },
   };
 }