agent-device 0.20.7 → 0.20.9

package/README.md

@@ -1,6 +1,6 @@
 <a href="https://www.callstack.com/open-source?utm_campaign=generic&utm_source=github&utm_medium=referral&utm_content=agent-device" align="center">
   <picture>
-    <img alt="agent-device: device automation CLI for AI agents" src="website/docs/public/agent-device-banner.jpg">
+    <img alt="agent-device: mobile app automation and verification for AI coding agents" src="website/docs/public/agent-device-banner.jpg">
   </picture>
 </a>
 
@@ -13,13 +13,13 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE)
 [![Glama MCP server](https://glama.ai/mcp/servers/callstack/agent-device/badges/score.svg)](https://glama.ai/mcp/servers/callstack/agent-device)
 
-Let your coding agent verify its changes in the running app.
+**Mobile app automation and verification for AI coding agents.** Give coding agents a live app feedback loop through a CLI, built-in MCP server, or typed Node.js API.
 
-`agent-device` lets coding agents inspect, control, and verify apps on iOS, Android, HarmonyOS, tvOS, Android TV, Amazon Vega OS TV through the Vega Virtual Device (VVD), web, macOS, and Linux. Agents can read token-efficient accessibility snapshots where supported, find elements by ref or selector, run device actions, and save evidence for review. HarmonyOS support uses HDC and ArkUI `uitest` on connected devices and DevEco emulators; use `capabilities --platform harmonyos` to inspect its evidence-backed command subset. Initial Vega OS support is VVD-only and covers discovery, app lifecycle, and complete TV-remote control; physical Fire TV, capture, and selector backends remain unsupported.
+<!-- Intro rule: category line, job pitch with the platform list, works-with/proof line, nothing else. Per-platform transports, tool names, vendor lists, and support caveats belong in "How it works" and website/docs, never here. Every name in the proof line must link to public evidence. -->
 
-Your coding agent or QA tool reads each result and chooses the next command. `agent-device` runs the command and saves evidence when asked.
+Let your coding agent verify its changes in the running app. `agent-device` lets agents inspect, control, debug, and verify apps on iOS, Android, and HarmonyOS (simulators, emulators, and physical devices), plus tvOS, Android TV, Amazon Vega OS TV (Vega Virtual Device), web, macOS, and Linux. Agents read token-efficient accessibility snapshots instead of reasoning over screenshots alone, act through refs and selectors, and save evidence for review. It also coordinates device access across parallel agent worktrees and connects to remote device clouds.
 
-`agent-device` uses the inspect-act-verify process from Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) for mobile, TV, and desktop apps. Basic `--platform web` support runs `agent-browser` in the same session and replay system.
+Works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP, or as the runtime under agents you build with the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) or [Eve](https://oss.callstack.com/agent-device/docs/eve). Developers at [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), and [others](#who-uses-agent-device) use it to verify their apps.
 
 ## Quick start
 
@@ -31,7 +31,9 @@ agent-device doctor
 agent-device help workflow
 ```
 
-Run `agent-device doctor` yourself before handing the CLI to an agent. The installed CLI help defines current behavior. `agent-device help workflow` links to guides for debugging, replay, React Native profiling, and other tasks.
+Run `doctor` yourself before handing the CLI to an agent; `help workflow` links to the guides for debugging, replay, and profiling, and the installed help always matches the installed version.
+
+### Drive an app from the CLI
 
 Add a contact in the built-in iOS Contacts app:
 
@@ -59,13 +61,46 @@ agent-device screenshot ./contact-form.png
 agent-device close
 ```
 
-Use refs only from the latest output. Do not assume an earlier `@eN` still identifies the same element. After a command with `--settle`, use the refs in its diff. Take another snapshot only if the diff omits what you need.
+Refs are only valid from the latest output: after a `--settle` command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.
 
-`--settle` works the same way on `scroll` and `back`, so scroll-then-observe and back-then-observe are one call too.
+![agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt](./website/docs/public/agent-device-contacts.gif)
 
-Snapshots use the app's accessibility tree. Clear labels, roles, and test IDs make agent runs more reliable. Use screenshots and videos as evidence or when accessibility data is poor. Use refs and selectors for actions and assertions when you can.
+### Add MCP tools to your agent
 
-![agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt](./website/docs/public/agent-device-contacts.gif)
+`agent-device mcp` starts the official stdio MCP server, exposing the installed commands as structured tools over the same execution path as the CLI:
+
+```json
+{
+  "mcpServers": {
+    "agent-device": {
+      "command": "agent-device",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) for per-client setup and when to prefer plain CLI over MCP.
+
+### Script it from Node.js
+
+`createAgentDeviceClient()` gives Node.js code typed access to the same commands, as model tools in your own agent or from orchestration code:
+
+```ts
+import { createAgentDeviceClient } from 'agent-device';
+
+const client = createAgentDeviceClient({ session: 'qa-run' });
+try {
+  await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
+  const snapshot = await client.capture.snapshot({ interactiveOnly: true });
+  const button = snapshot.nodes.find((node) => node.role === 'button');
+  if (button) await client.interactions.press({ ref: button.ref });
+} finally {
+  await client.sessions.close();
+}
+```
+
+See the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api), the [runnable examples](https://github.com/callstack/agent-device/tree/main/examples/sdk), and the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) and [Eve](https://oss.callstack.com/agent-device/docs/eve) integration guides.
 
 ## What agents can do
 
@@ -78,58 +113,86 @@ See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the com
 
 ![Diagram of the agentic development loop: humans assign tasks, agents write and review code, agent-device verifies mobile apps, pull requests receive evidence, and bugs or performance issues lead to fixes](./website/docs/public/agentic-development-loop.svg)
 
-## Next steps
-
-- **Set up your agent**: run the CLI from Cursor, Codex, Claude Code, Windsurf, or another agent terminal. See [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) for skills, rules, MCP tools, and setup for each client.
-- **Try the sample app**: clone the repo and run the bundled Expo test app. [Quick Start](https://oss.callstack.com/agent-device/docs/quick-start) covers a guided run with screenshots, replay, and performance data.
-- **Build repeatable tests**: use [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) to repeat tests. Use [Debugging & Profiling](https://oss.callstack.com/agent-device/docs/debugging-profiling) to find bugs.
+## What to ask your agent
 
-## Articles and videos
+With the CLI installed, prompts like these work end to end:
 
-### Articles
+- "Implement the onboarding screen, run it on the iOS simulator and Android emulator, and attach screenshots."
+- "Reproduce this crash and capture the logs that lead up to it."
+- "Check whether this change causes unnecessary React Native re-renders."
+- "Explore the checkout flow once, save it as a replay script, and run it in CI."
+- "Verify this pull request on a physical device and attach reviewable evidence."
 
-- [Build an AI QA agent for Expo apps with EAS Workflows](https://expo.dev/blog/build-an-ai-qa-agent-for-expo-apps-with-eas-workflows-in-minutes-today)
-- [Agent Device: iOS & Android automation for AI agents](https://www.callstack.com/blog/agent-device-ai-native-mobile-automation-for-ios-android)
-- [Building mobile QA agents with Vercel Eve](https://www.callstack.com/blog/building-reviewable-mobile-qa-agents-with-vercel-eve)
-- [How we optimized Agent Device for mobile app automation](https://www.callstack.com/blog/how-we-optimized-agent-device-for-mobile-app-automation)
-
-### Videos
+## Next steps
 
-- [Verifying mobile apps with agent-device](https://youtu.be/kZDU-k5r9kE)
-- [Using agent-device in an AI coding workflow](https://youtu.be/dfVG_aNPkW4)
-- [Cloud agents that test mobile apps on real devices](https://youtu.be/r5P0detC4bs?is=_KB6SZbLFRB1au_z)
+- [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup): skills, project rules, and per-client setup for Cursor, Codex, Claude Code, Windsurf, and others.
+- [Quick Start](https://oss.callstack.com/agent-device/docs/quick-start): a guided run on the bundled Expo test app with screenshots, replay, and performance data.
+- [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) and [Debugging & Profiling](https://oss.callstack.com/agent-device/docs/debugging-profiling): repeatable tests and bug hunting.
 
 ## Where to run agent-device
 
+The same session and evidence model works at every step: the agent explores the app, captures evidence, saves a replay, runs it in CI, and moves onto remote devices.
+
 | Path | Best for | Start with |
 | --- | --- | --- |
 | Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. |
-| CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). GitHub Actions template coming soon. |
-| Cloud / remote | Linux runners, managed devices, and remote jobs. | Use [Agent Device Cloud](https://agent-device.dev/cloud), set a remote profile with [Commands](https://oss.callstack.com/agent-device/docs/commands), or [contact Callstack](mailto:hello@callstack.com) for team QA. |
+| CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). |
+| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://oss.callstack.com/agent-device/docs/remote-proxy), connect a [device cloud](https://oss.callstack.com/agent-device/docs/device-clouds) (BrowserStack, AWS Device Farm, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. |
 
 ## How it works
 
 `agent-device` keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, HDC and ArkUI `uitest` on HarmonyOS, Vega CLI/VDA on the Vega Virtual Device, a local helper on macOS, and AT-SPI on Linux.
 
-Node.js apps can use the typed client or public subpaths. `agent-device/android-adb` provides the Android ADB provider interface, helpers for logcat, the clipboard, the keyboard, and apps, and port reverse management.
+Support depth varies by target. Newer backends such as HarmonyOS and Vega OS cover a subset of commands; run `agent-device capabilities --platform <platform>` to see what a target supports.
+
+Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. The same commands drive hosted devices on [BrowserStack, AWS Device Farm, and Limrun](https://oss.callstack.com/agent-device/docs/device-clouds).
+
+`agent-device` uses the inspect-act-verify process from Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) for mobile, TV, and desktop apps. Basic `--platform web` support runs `agent-browser` in the same session and replay system.
 
 ## FAQ
 
 ### What is agent-device?
 
-`agent-device` is a command-line tool that lets coding agents inspect, control, and verify apps and save evidence for review. It supports iOS, Android, HarmonyOS, TV, web, macOS, and Linux.
+`agent-device` is a command-line tool and MCP server that lets AI coding agents inspect, control, and verify mobile apps and save evidence for review. It supports iOS, Android, HarmonyOS, TV, web, macOS, and Linux.
+
+### Is there an MCP server for mobile app automation?
+
+Yes. `agent-device mcp` starts the official stdio MCP server. The Quick start above has the client config, and [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup) covers per-client details.
 
 ### Does it work with React Native, Expo, Flutter, and native apps?
 
 Yes. `agent-device` supports native iOS and Android apps, plus React Native, Expo, and Flutter apps on supported targets. The commands and evidence vary by target.
 
+### How is it different from mobile MCP servers?
+
+The MCP server is one entry point to the same runtime used by the CLI and typed Node.js API. Sessions, device ownership, selectors, evidence, replay, CI workflows, and cloud routing stay consistent across all three.
+
+### Can I build my own agent or QA product on agent-device?
+
+Yes. The typed Node.js client is a public surface over that same runtime, so an agent you build inherits everything above. Start from the [Node.js API](https://oss.callstack.com/agent-device/docs/client-api), [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk), or [Eve](https://oss.callstack.com/agent-device/docs/eve) guides.
+
 ### How is it different from Appium, Detox, or Maestro?
 
 With `agent-device`, an agent reads app state and chooses each command at run time. Teams use Appium, Detox, and Maestro to write and maintain test suites. `agent-device` can complement them by saving its runs as `.ad` scripts or exporting them as strict Maestro YAML.
 
 ### Can agent-device run in CI?
 
-Yes. Record a run as an `.ad` script, replay it locally or in CI, and save screenshots, logs, and other artifacts for review. See [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) or start with the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml).
+Yes. Record a run as an `.ad` script, replay it in CI, and keep the screenshots and logs as artifacts; the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml) is a working example.
+
+## Articles and videos
+
+### Articles
+
+- [Build an AI QA agent for Expo apps with EAS Workflows](https://expo.dev/blog/build-an-ai-qa-agent-for-expo-apps-with-eas-workflows-in-minutes-today)
+- [Agent Device: iOS & Android automation for AI agents](https://www.callstack.com/blog/agent-device-ai-native-mobile-automation-for-ios-android)
+- [Building mobile QA agents with Vercel Eve](https://www.callstack.com/blog/building-reviewable-mobile-qa-agents-with-vercel-eve)
+- [How we optimized Agent Device for mobile app automation](https://www.callstack.com/blog/how-we-optimized-agent-device-for-mobile-app-automation)
+
+### Videos
+
+- [Verifying mobile apps with agent-device](https://youtu.be/kZDU-k5r9kE)
+- [Using agent-device in an AI coding workflow](https://youtu.be/dfVG_aNPkW4)
+- [Cloud agents that test mobile apps on real devices](https://youtu.be/r5P0detC4bs?is=_KB6SZbLFRB1au_z)
 
 ## Who uses agent-device?
 

package/android/ime-helper/dist/agent-device-android-ime-helper-0.20.9.apk.sha256

@@ -0,0 +1 @@
+f98ded51f104c10268a75b7eb77f2e479461b844e49f238593d44b821d13e294  agent-device-android-ime-helper-0.20.9.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.20.7.manifest.json → agent-device-android-ime-helper-0.20.9.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-ime-helper",
-  "version": "0.20.7",
-  "assetName": "agent-device-android-ime-helper-0.20.7.apk",
-  "sha256": "7311d6a527bdf8be33b752e59e73f4a527585654f8d530d3680ab15ccf271cb0",
+  "version": "0.20.9",
+  "assetName": "agent-device-android-ime-helper-0.20.9.apk",
+  "sha256": "f98ded51f104c10268a75b7eb77f2e479461b844e49f238593d44b821d13e294",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 20007,
+  "versionCode": 20009,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

package/android/snapshot-helper/dist/agent-device-android-snapshot-helper-0.20.9.apk.sha256

@@ -0,0 +1 @@
+a5169f62fb38bb1980cf7c7963542f2bc5bbaafd4d9dc7b5b23d3e41ee782725  agent-device-android-snapshot-helper-0.20.9.apk

package/android/snapshot-helper/dist/{agent-device-android-snapshot-helper-0.20.7.manifest.json → agent-device-android-snapshot-helper-0.20.9.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.20.7",
-  "releaseTag": "v0.20.7",
-  "assetName": "agent-device-android-snapshot-helper-0.20.7.apk",
+  "version": "0.20.9",
+  "releaseTag": "v0.20.9",
+  "assetName": "agent-device-android-snapshot-helper-0.20.9.apk",
   "apkUrl": null,
-  "sha256": "c45f72eea93c19b4a17fedb4b25f880d5e225c9ab41be4017db8613fdd276e09",
-  "checksumName": "agent-device-android-snapshot-helper-0.20.7.apk.sha256",
+  "sha256": "a5169f62fb38bb1980cf7c7963542f2bc5bbaafd4d9dc7b5b23d3e41ee782725",
+  "checksumName": "agent-device-android-snapshot-helper-0.20.9.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 20007,
+  "versionCode": 20009,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAXSnapshotBridge.h

@@ -97,6 +97,9 @@ FOUNDATION_EXPORT NSString *const RunnerAXSnapshotCustomActionsBlockedKey;
 /// adds no work", which is only observable as this counter standing still.
 + (NSInteger)customActionReadDispatchCount;
 
+/// Total reads refused by single-flight admission.
++ (NSInteger)customActionReadBlockedCount;
+
 /// The shared AX client (`XCUIDevice.accessibilityInterface`), or nil when the
 /// private interface is unavailable.
 + (nullable id)accessibilityClient;

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAXSnapshotBridge.m

@@ -63,6 +63,9 @@ static atomic_int RunnerAXCustomActionReadsInFlight = 0;
 /// staying put, so it is recorded rather than inferred.
 static atomic_long RunnerAXCustomActionReadDispatches = 0;
 
+/// Total single-flight admission refusals.
+static atomic_long RunnerAXCustomActionReadBlocked = 0;
+
 /// Output caps. The element budget bounds how many elements we read; these
 /// bound what any ONE element can put in the response, so a pathological app
 /// cannot spend the whole snapshot on one node's action list.
@@ -514,17 +517,15 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
   if (![axClient respondsToSelector:selector]) {
     return nil;
   }
-  // Single flight. An abandoned read still owns the serial queue, so
-  // dispatching here would only queue work behind it — and repeating the
-  // capture would keep queueing more. Refuse without dispatching instead.
-  if (atomic_load(&RunnerAXCustomActionReadsInFlight) > 0) {
-    NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_CUSTOM_ACTIONS_READ_BLOCKED");
+  int expectedReadsInFlight = 0;
+  if (!atomic_compare_exchange_strong(
+        &RunnerAXCustomActionReadsInFlight, &expectedReadsInFlight, 1)) {
+    atomic_fetch_add(&RunnerAXCustomActionReadBlocked, 1);
     return nil;
   }
   // The AX call is a synchronous XPC round trip with no timeout of its own, so
   // it runs off-thread behind a bounded wait. On timeout the result box is
   // never read, so a late-returning wedged call cannot race this thread.
-  atomic_fetch_add(&RunnerAXCustomActionReadsInFlight, 1);
   atomic_fetch_add(&RunnerAXCustomActionReadDispatches, 1);
   NSMutableArray *box = [NSMutableArray array];
   dispatch_semaphore_t finished = dispatch_semaphore_create(0);
@@ -543,7 +544,7 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
     }
     // Clear in-flight BEFORE signalling, so a waiter that wakes on this signal
     // never observes its own completed read as still outstanding.
-    atomic_fetch_sub(&RunnerAXCustomActionReadsInFlight, 1);
+    atomic_store(&RunnerAXCustomActionReadsInFlight, 0);
     dispatch_semaphore_signal(finished);
   });
   long waited = dispatch_semaphore_wait(
@@ -622,6 +623,11 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
   return (NSInteger)atomic_load(&RunnerAXCustomActionReadDispatches);
 }
 
++ (NSInteger)customActionReadBlockedCount
+{
+  return (NSInteger)atomic_load(&RunnerAXCustomActionReadBlocked);
+}
+
 + (nullable id)accessibilityClient
 {
   return [self objectFrom:XCUIDevice.sharedDevice selectorName:@"accessibilityInterface"];

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift

@@ -175,15 +175,10 @@ extension RunnerTests {
 
       let rootFrame = privateAXRect(root["frame"])
       let viewport = privateAXSnapshotViewport(app: app, rootFrame: rootFrame)
-      var nodes: [SnapshotNode] = []
-      appendPrivateAXNode(
-        root,
-        to: &nodes,
+      let nodes = privateAXPresentation(
+        rawRoot: root,
         options: options,
-        viewport: viewport,
-        depth: 0,
-        parentIndex: nil,
-        insideMatchedScope: false
+        viewport: viewport
       )
       if nodes.count <= 1 {
         NSLog("AGENT_DEVICE_RUNNER_PRIVATE_AX_SNAPSHOT_SPARSE=%ld", nodes.count)
@@ -250,110 +245,7 @@ extension RunnerTests {
     }
   }
 
-  private func appendPrivateAXNode(
-    _ rawNode: [String: Any],
-    to nodes: inout [SnapshotNode],
-    options: SnapshotOptions,
-    viewport: CGRect,
-    depth: Int,
-    parentIndex: Int?,
-    insideMatchedScope: Bool
-  ) {
-    if let limit = options.depth, depth > limit { return }
-
-    let rect = privateAXRect(rawNode["frame"])
-    let label = privateAXString(rawNode["label"])
-    let identifier = privateAXString(rawNode["identifier"])
-    let value = privateAXString(rawNode["value"])
-    let rawType = privateAXInt(rawNode["type"]) ?? 0
-    let typeName = elementTypeName(rawElementType: rawType)
-    let enabled = privateAXBool(rawNode["enabled"]) ?? true
-    let visible = isVisibleInViewport(rect, viewport)
-    let interactiveCandidate = privateAXInteractiveCandidate(rawElementType: rawType)
-    let filterDecision = flatSnapshotFilterDecision(
-      FlatSnapshotFilterNode(
-        isRoot: parentIndex == nil,
-        label: label,
-        identifier: identifier,
-        valueText: value.isEmpty ? nil : value,
-        visible: visible
-      ),
-      options: options,
-      insideMatchedScope: insideMatchedScope
-    )
-    let include = filterDecision.include
-    let nowInsideScope = filterDecision.insideMatchedScope
-
-    let currentIndex: Int?
-    if include {
-      currentIndex = nodes.count
-      nodes.append(
-        SnapshotNode(
-          index: nodes.count,
-          type: typeName,
-          label: label.isEmpty ? nil : label,
-          identifier: identifier.isEmpty ? nil : identifier,
-          value: value.isEmpty ? nil : value,
-          rect: snapshotRect(from: rect),
-          enabled: enabled,
-          focused: privateAXBool(rawNode["focused"]) == true ? true : nil,
-          selected: privateAXBool(rawNode["selected"]) == true ? true : nil,
-          hittable: visible && enabled && interactiveCandidate,
-          depth: depth,
-          parentIndex: parentIndex,
-          hiddenContentAbove: nil,
-          hiddenContentBelow: nil,
-          actions: rawNode["actions"] as? [String]
-        )
-      )
-    } else {
-      currentIndex = parentIndex
-    }
-
-    guard let children = rawNode["children"] as? [[String: Any]] else {
-      return
-    }
-    for child in children {
-      appendPrivateAXNode(
-        child,
-        to: &nodes,
-        options: options,
-        viewport: viewport,
-        depth: depth + 1,
-        parentIndex: currentIndex,
-        insideMatchedScope: nowInsideScope
-      )
-    }
-  }
-
-  private func elementTypeName(rawElementType: Int) -> String {
-    if let type = flatSnapshotElementType(rawElementType: rawElementType) {
-      return elementTypeName(type)
-    }
-    return "Element(\(rawElementType))"
-  }
-
-  private func privateAXString(_ value: Any?) -> String {
-    guard let value else { return "" }
-    if let string = value as? String {
-      return string.trimmingCharacters(in: .whitespacesAndNewlines)
-    }
-    return String(describing: value).trimmingCharacters(in: .whitespacesAndNewlines)
-  }
-
-  private func privateAXInt(_ value: Any?) -> Int? {
-    if let value = value as? Int { return value }
-    if let value = value as? NSNumber { return value.intValue }
-    return nil
-  }
-
-  private func privateAXBool(_ value: Any?) -> Bool? {
-    if let value = value as? Bool { return value }
-    if let value = value as? NSNumber { return value.boolValue }
-    return nil
-  }
-
-  private func privateAXRect(_ value: Any?) -> CGRect {
+  func privateAXRect(_ value: Any?) -> CGRect {
     guard let frame = value as? [String: Any] else {
       return .zero
     }

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -761,7 +761,11 @@ extension RunnerTests {
       }
     case .recordStop:
       guard let recorder = activeRecording else {
-        return Response(ok: false, error: ErrorPayload(message: "no active recording"))
+        // The runner protocol is the durable cleanup primitive. A daemon may crash after the
+        // native stop succeeds but before it commits the resource transition, so exact-owner
+        // recovery must be able to repeat this command safely. Public `record stop` still owns
+        // its user-facing no-active validation through the daemon session manifest.
+        return Response(ok: true, data: DataPayload(message: "recording already stopped"))
       }
       do {
         try recorder.stop()

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+FlatSnapshotFiltering.swift

@@ -18,10 +18,16 @@ struct FlatSnapshotFilterDecision {
   let insideMatchedScope: Bool
 }
 
+enum FlatSnapshotVisibilityPolicy {
+  case interactiveOnly
+  case viewportProjected
+}
+
 extension RunnerTests {
   func flatSnapshotFilterDecision(
     _ node: FlatSnapshotFilterNode,
     options: SnapshotOptions,
+    visibilityPolicy: FlatSnapshotVisibilityPolicy,
     insideMatchedScope: Bool
   ) -> FlatSnapshotFilterDecision {
     let scope = options.scope?.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -39,7 +45,9 @@ extension RunnerTests {
       include = true
     } else if scopeActive && !nowInsideScope {
       include = false
-    } else if options.interactiveOnly && !node.visible {
+    } else if !node.visible
+      && (options.interactiveOnly || visibilityPolicy == .viewportProjected)
+    {
       include = false
     } else {
       include = true

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+PrivateAXPresentation.swift

@@ -0,0 +1,90 @@
+import XCTest
+
+extension RunnerTests {
+  func privateAXPresentation(rawRoot: [String: Any], options: SnapshotOptions, viewport: CGRect)
+    -> [SnapshotNode]
+  {
+    var nodes: [SnapshotNode] = []
+    var hints: [Int: (above: Bool, below: Bool)] = [:]
+    appendPrivateAXNode(rawRoot, to: &nodes, hints: &hints, options: options, viewport: viewport,
+      depth: 0, parentIndex: nil, insideMatchedScope: false, scrollContext: nil)
+    return applyHiddenContentHints(hints, to: nodes)
+  }
+
+  private func appendPrivateAXNode(_ raw: [String: Any], to nodes: inout [SnapshotNode],
+    hints: inout [Int: (above: Bool, below: Bool)], options: SnapshotOptions, viewport: CGRect,
+    depth: Int, parentIndex: Int?, insideMatchedScope: Bool,
+    scrollContext: (index: Int, rect: CGRect)?)
+  {
+    if let limit = options.depth, depth > limit { return }
+    let rect = privateAXRect(raw["frame"])
+    let label = privateAXPresentationString(raw["label"])
+    let identifier = privateAXPresentationString(raw["identifier"])
+    let value = privateAXPresentationString(raw["value"])
+    let rawType = privateAXPresentationInt(raw["type"]) ?? 0
+    let enabled = privateAXPresentationBool(raw["enabled"]) ?? true
+    let children = raw["children"] as? [[String: Any]] ?? []
+    let elementType = flatSnapshotElementType(rawElementType: rawType)
+    let hasFrame = !rect.isNull && !rect.isEmpty
+    let onScreen = hasFrame
+      && isVisibleInRegularSnapshot(
+        rect,
+        viewport: viewport,
+        scrollContainerAnchor: scrollContext
+      )
+    let presentationVisible = !hasFrame || onScreen
+    let decision = flatSnapshotFilterDecision(
+      FlatSnapshotFilterNode(isRoot: parentIndex == nil, label: label, identifier: identifier,
+        valueText: value.isEmpty ? nil : value, visible: presentationVisible),
+      options: options, visibilityPolicy: .viewportProjected,
+      insideMatchedScope: insideMatchedScope)
+    let include = decision.include
+
+    if !presentationVisible, let scrollContext {
+      rememberHiddenContentHint(for: rect, relativeTo: scrollContext, hints: &hints)
+    }
+
+    let currentIndex: Int?
+    if include {
+      currentIndex = nodes.count
+      let typeName = elementType.map(elementTypeName) ?? "Element(\(rawType))"
+      nodes.append(SnapshotNode(index: nodes.count, type: typeName,
+        label: label.isEmpty ? nil : label, identifier: identifier.isEmpty ? nil : identifier,
+        value: value.isEmpty ? nil : value, rect: snapshotRect(from: rect), enabled: enabled,
+        focused: privateAXPresentationBool(raw["focused"]) == true ? true : nil,
+        selected: privateAXPresentationBool(raw["selected"]) == true ? true : nil,
+        hittable: onScreen && enabled && privateAXInteractiveCandidate(rawElementType: rawType),
+        depth: depth, parentIndex: parentIndex, hiddenContentAbove: nil, hiddenContentBelow: nil,
+        actions: raw["actions"] as? [String]))
+    } else { currentIndex = parentIndex }
+
+    let nextScrollContext: (index: Int, rect: CGRect)?
+    if include, let elementType, let currentIndex {
+      nextScrollContext = scrollContainerAnchor(
+        for: elementType,
+        hasChildren: !children.isEmpty,
+        visible: onScreen,
+        frame: rect,
+        nodeIndex: currentIndex
+      ) ?? scrollContext
+    } else { nextScrollContext = scrollContext }
+    for child in children {
+      appendPrivateAXNode(child, to: &nodes, hints: &hints, options: options, viewport: viewport,
+        depth: depth + 1, parentIndex: currentIndex,
+        insideMatchedScope: decision.insideMatchedScope, scrollContext: nextScrollContext)
+    }
+  }
+
+  private func privateAXPresentationString(_ value: Any?) -> String {
+    guard let value else { return "" }
+    return (value as? String ?? String(describing: value))
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+  }
+  private func privateAXPresentationInt(_ value: Any?) -> Int? {
+    (value as? Int) ?? (value as? NSNumber)?.intValue
+  }
+  private func privateAXPresentationBool(_ value: Any?) -> Bool? {
+    (value as? Bool) ?? (value as? NSNumber)?.boolValue
+  }
+}
+

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+RecordingTests.swift

@@ -0,0 +1,4 @@
+import XCTest
+
+extension RunnerTests {
+}