-
Fixed (mobile): a
get,is,find, orwaitselector read no longer answers from a tree that a later command outdated. Selector reads reuse the session's stored tree for 750 ms after its capture. Two cases outdated that tree without replacing it: await textsatisfied by the owner's native text reading after an earlier miss capture, and a mutation that captured nothing (for example a coordinatepress). The next read then reused the pre-change tree and could reportSelector did not matchfor an element that was on screen. A side effect or a native read now retires the stored tree, and the next read captures again. -
Fixed (mobile): a read taken right after a
scroll,swipe, orgesture swipeno longer reports a definite miss when the surface never settled. When post-gesture stabilization ran out of budget on a surface still moving,is visibleanswered a plainselector_not_foundandis absentpassed. That capture now carriesunsettledGesture:is,get,find, andwaitreport it (inerror.detailsordata) with an appended warning,snapshotappends the warning,is absentrefuses withobservation: "unsettled",wait absentkeeps polling, and the next read captures afresh. Click, press, and fill by selector do not disclose it yet. A failed read now also carriestargetActivationinerror.details, the same place asunsettledGesture. -
Fixed (ios):
openon a local Simulator now waits for the launched app's discovery before it decides whether the app is observable. On a loaded hostsimctl spawn launchctl listoutlasts one 1.5 s discovery wait slice, and the launch observation read that slice as an unobservable app, so the open returned before the discovery, the AX-bridge preparation or the first bridge connection. The firstwaitafter the open then paid all three in one poll, behind a runnerfindText, and on CI it spent its whole 10 s budget there (wait_capture_stalledwithcaptures: 1). The probe now joins the running discovery, bounded by the discovery's own deadline, and then observes the launch as before. A resolution failure other than a pending discovery still ends the probe at once. -
Fixed (ios):
alert acceptandalert dismissno longer land their tap after the command's deadline when a notification banner is on screen. XCTest checks for SpringBoard banners and alerts before every event and its default handler waited up to 15 s for a banner to leave, so the command answeredALERT_DEADLINE_EXCEEDED("The button was activated once") for a tap that arrived after the caller was told it had failed (#2546's late tap, from the banner side). Alert activation now opts out of XCTest's interruption handling, which also stops that handler from pressing a button of its own choosing on an unrelated system alert while the command answers the alert it resolved. -
Fixed (macos):
screenshot --fullscreenon thedesktop,menubar, orfrontmost-appsurface now refuses withINVALID_ARGS(details.reason: SCREENSHOT_FULLSCREEN_MACOS_HELPER_SURFACE_FIXED_FRAME) instead of being accepted and silently ignored. Every one of those surfaces captures through the macOS helper, which always reads the main display, so the flag never named a frame the capture could vary. A.adscript or project config that setsscreenshotFullscreenfor one of those surfaces now fails instead of succeeding with the same image it always produced; drop the flag there. macOS app sessions and every other platform keep accepting--fullscreenunchanged. (#2799) -
Fixed (ios): no runner read launches a session app that is not running anymore. The XCTest runner repaired foreground loss by calling
activate(), which launches an app that is not running. Afteropen <app> --relaunch --launch-url <url>on a Simulator, iOS can hold the launch behind an "Open in …?" confirmation, and the first read of the waiting session launched the app without the URL. Reads —snapshot,wait,is,get, a readingfind, and an interaction's leading reads (the viewport read agesturestarts with, the capture that resolves a selectorclick/fill) — now refuse withCOMMAND_FAILED,details.runnerErrorCode: "APP_NOT_RUNNING",retriable: trueand a hint to answer the prompt withalert acceptor relaunch withopen. Awaitpolls through the refusal; the runner transport never resends it. Interactions that mutate without a leading read (press, a coordinatefill,swipe,scroll, hardware keys) keep the foreground repair and still bring a stopped app up. -
Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again publishes the geometric
hittablefact, sois hittableand ahittable:selector resolve the same controls on the bridge and the XCTest runner. The snapshot capability table has declaredhittable = geometric-actionabilityfor every backend (#1933), and the runner has always stamped it; when 0.21.0 made the AX bridge the Simulator's snapshot source, the bridge reader mapped the traits word intoenabledandselectedbut handed over no hit result and disclosedhittabilityas unavailable on every capture, so ahittable:selector matched nothing on the bridge that the runner would match. The reader now deriveshittableon its raw nodes from the same rule the runner's Swift uses — the sharedisGeometricallyActionable,CGRect.containshalf-open edges and all — applied to the node's own frame and the reported viewport, and discloseshittabilityas unavailable only when no viewport is reported. Because it stamps the raw source rather than the fold,snapshot --rawmatches too, and the residue owner stays the fact owner (#2199). Closes the hittable-absence half of the AX-bridge capture divergence (#2638). -
Fixed (web):
press --doubleandpress --holdon a web session now answer with a typed reason instead of an unclassifiedUNSUPPORTED_OPERATIONnaming an interactor member. The browser owner'stapPointcell admitted the whole press series, but the web click affordance is one immediate pointer press per call:--countrepeats it, and this owner composes neither a fused double-click nor a timed hold. A hold is refused by thelongPressPointcell that already refuseslongpress, so both commands now carry the hint "A web click is one immediate pointer press; the browser backend has no timed hold." andpress --holdaddsdetails.reason: "unsupported-platform-leaf". A double-click is refused by the fused mechanic the web interactor no longer carries, reportingdetails.reason: "owner-capability-missing"; both refusals arrive when the press runs, after any target selector was resolved. A repeated single-tap press (--count 3) keeps working on the same session, and every owner that double-tapped or held before this change still does: Android, iOS, Linux, HarmonyOS, Cloud WebDriver and Limrun keep their own mechanics, and an owner with a fused point press keeps answering--doublethrough it. -
Fixed (ios): a local Simulator snapshot taken through the host AX bridge once again carries the accessibility
selectedstate, sois selected, aselected=trueselector, and a Maestroselected:qualifier match the active control. When 0.21.0 made the AX bridge the Simulator's snapshot source, the bridge's node reader mapped the traits word intoenabledbut never intoselected, so an active bottom tab, chosen segment, or checked row published noselectedfield and everyselected:match failed on the iOS Simulator — a fact the 0.20.x XCTest tree had always supplied and thatsnapshots.mdstill promises. The reader now derivesselectedfrom the selected-trait bit of the same traits word, publishingselected: trueonly when set and omitting it otherwise so the two producers cannot be told apart by aselected:selector. The bit is pinned by the guest's real captured words, so a producer encoding change cannot drop the fact silently again. -
Fixed (ios): an interactive snapshot no longer drops the rows of a list whose row hosts a scroll view of its own. Ownership of a scroll indicator is now read from its parent edge — a visible band derives only when the indicator's parent is itself a scroll type — instead of walking ancestors for the nearest scrollable or text node. #2740 closed the class for
TextViewalone; the walk still misattributed the indicator of any other scroll-shaped host that publishes as a non-scroll type (aWebView, a map view, a paged cell) to the enclosing list and clipped that list to the host's one-line band. Ownership still passes up through ancestors that share the scroller's exact frame, so aWKWebViewpage — whose indicator sits underWebViewwrappers that fill the scroll view — keeps its visible band; the walk stops at the first frame change, so a host smaller than its list still owns nothing. ADR 0026. -
Fixed (ios):
fold half-openno longer reports a pose the hinge never held. The command accepted the requested category as the answer whenever its four-read budget happened to end on ahalf-openangle, so a hinge still sweeping from 180° toward 0° — which passes through every half-open angle on the way — came back as a settled Book pose. An angle inside that open interval proves the category and nothing else, sohalf-opennow requires two consecutive readings that both fall inside it and agree within 0.5°; a pair straddling the 179° boundary is two poses, not one hinge at rest. A budget ending on an unsettled angle fails withCOMMAND_FAILEDanddetails.reason: "fold-pose-unsettled", carryingrequestedPose,observedPose,hingeAngleDegreesand the previous reading, and says the hinge was observed half-open and did not settle rather than claiming it never got there.fold-pose-unverifiedstill covers a budget that ends on another pose. Supersedes ADR 0025's budget-end exception (#2730). -
Fixed (ios): an interactive snapshot of a list whose row holds selectable text (a
TextView) no longer drops every row after that text. A UITextView is a scroll view too, and XCTest publishes its scroll indicator inside the text; the presentation read that indicator onto the list around it and clipped the list's viewport to one line, so a post thread whose root post is selectable text showed the root and none of its replies, while the full snapshot showed all of them. An indicator whose nearest scrolling ancestor is a text view now belongs to that text view and derives no list viewport. -
Fixed (ios): a foreground repair names the state the session app was really in. The decoder translated the runner's raw
XCApplicationStateinteger from a handwritten table that hadrunningBackgroundSuspended(2) andrunningBackground(3) the wrong way round, so a suspended app was disclosed as merely backgrounded intargetActivation.priorStateand in the appended warning — as shipped in v0.21.7 and v0.21.8. The table now follows what the SDK declares, a runner XCTest pins every integer againstXCUIApplication.Stateitself, and the decoder test reads those pins, so the two copies cannot drift apart unnoticed. -
Fixed (macos):
pressandclickon thefrontmost-app,desktop, andmenubarsurfaces post clicks the way a trackpad does. The helper posted the release in the same tick as the press, so AppKit dropped it and controls never activated; each press is now held (--hold-ms, 60 ms by default, 40 ms at least).--countis that many independent clicks and--double-tapposts each as a double-click pair, the helper's deadline follows the click schedule instead of a fixed 30 s, and every stop the host applies mid-hold — a cancelled request, a dropped client, the deadline — reaches the helper as SIGTERM first so it releases the button before it exits; SIGKILL only follows a helper that has not exited a second later. -
Added (ios):
fold <closed|half-open|open>andclient.command.fold({ pose })put a foldable iPhone simulator (iPhone Duo) into a hinge pose. ADR 0025 recorded that no official host API sets the pose and left it to the operator; the pose is now set the way the operator did it, by pressing the pose control in the Xcode Device Hub window through macOS accessibility, and it is confirmed the way ADR 0025 asked for, by reading the hinge angle back from CoreDevice (devicectl device motion hinge-angle) until it agrees with the request. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, so an agent can see the lit panel changed without another capture. The macOS helper gained adevice-hub posesubcommand that finds Device Hub in the process table (LaunchServices registers the trampolined app with no pid), reopens its window when it shows none, and selects the simulator through the sidebar row keyed by its UDID so two simulators sharing a name cannot be confused. Simulator-only; a single-panel simulator refuses withUNSUPPORTED_OPERATION, and every other platform states its own refusal cell. -
Fixed (ios): the
foldresponse'sscreendimensions now match their coordinate-space contract. They are the lit panel's own native points (pixels divided by its point scale, never rotated), so the response carries thecoordinateSpace: "native-panel"discriminator and the docs no longer claim they are the next snapshot's coordinates. They cannot place a tap; take a fresh snapshot for the app viewport. -
Added (diff):
diff screenshotaccepts a JPEG baseline or current image. Both inputs had to be PNG, so a capture exported by another tool had to be converted first and a HarmonyOS capture — which the platform serves as JPEG under whatever name the command was given — could never be compared. Each input is now decoded from its own bytes, so the container is sniffed and a.pngname holding JPEG decodes as JPEG.png-transcode.tsbecamescreenshot-image.ts, the one owner of that sniffing for both the decode and the provider transcode path, and the PNG worker gained adecode-imagejob that answers pixels instead of PNG bytes. The--outdiff image stays PNG, as do the crop, overlay, and resize passes that rewrite a screenshot in place and could not survive a lossy container. -
Added (maestro):
setPermissionsandlaunchApp.permissionssupportall: allow|deny|unseton iOS simulators and Android, with specific entries overridingall. Both accept a Maestro-style permissions map. Entries apply in order until the selected platform refuses one, and the error then names what landed. Android's only allow level is while-in-use, solocation: inuse|neverapplyallow/denythere;location: alwaysandphotos: limitedstay Apple-only. -
Fixed (ios):
settings permissionno longer refuses a privacy service thatsimctl privacyaccepts but omits from its own help text — Xcode 26 does that forcamera, sosettings permission grant cameraand a Maestrocamera: allowfailed as unsupported while the raw command worked. Support is nowsimctl privacy's own verdict per runtime, and a service it refuses fails withUNSUPPORTED_OPERATION. This also drops the cachedsimctl privacy helpprobe and theprivacy helpspawn before the first permission change. iOSallstill does not cover notifications: current runtimes have no notifications service, so a targeted notifications change fails loudly andallleaves it unchanged. -
Added (limrun):
record startandrecord stopon Limrun iOS and Android direct sessions. The runtime declared recording unavailable although the Limrun SDK exposes a server-side recorder. Start asks the instance to record (--quality mediummaps to Limrun quality 5,highto 8); stop asks the instance to stop once, then downloads the served MP4 to the output path as a separate bounded step, so a dropped transfer is retried by the nextrecord stopwithout a second remote stop. The capture is always the whole simulator or emulator screen;--fpsand--hide-touchesare refused, and a recording cannot be reattached after a daemon restart. The web recorder now shares the same transport-recording runtime. -
Added (ios):
action-buttonpresses the iPhone or iPad Action Button once, andclient.command.actionButton()does the same. XCUITest exposesXCUIDevice.press(.action)with no hold-duration overload, so there is nolong-pressand no--duration-ms, and the slide surface on the same edge is Camera Control, which this command does not drive. The press is dispatched without the runner's app-activation preflight and with no post-action observation, so the session app keeps the state the press found; the runner asks the device for the button withhasHardwareButton(.action)and refuses withUNSUPPORTED_OPERATIONon a model that has none, and Android, HarmonyOS, Vega, Linux, web, tvOS, macOS, and visionOS each state their own refusal. Simulators run no Shortcuts or App Intents, so what a press triggers is verifiable only on a physical iPhone (#2699). -
Changed (all):
home,app-switcherandaction-buttonare one system-button family in the runtime contract. An owner without a button now refuses it with the family's hint (for exampleAndroid has no key event for this system button.) rather than a per-button sentence, and a Limrun or WebDriver session that is no longer active refusesaction-buttonwith that session's own reason like every other cell; the command name still leads theUNSUPPORTED_OPERATIONmessage. -
Fixed (android):
clipboard readandclipboard writestop reporting success on a build whose clipboard service has no shell command. Android 16 (API 36) answers everyadb shell cmd clipboard …with the framework defaultBinder.handleShellCommand—No shell command implementation.on stderr and exit status 0 — and the exit status was consulted first, so a read reportedtext: "", a write reported "Clipboard updated", andcapabilitiesadvertisedclipboardon a clipboard no adb call ever touched. The response is now classified per stream into one typed verdict shared by both legs and the capability probe: the service's own sentence onstderroutranks a clean exit (a service that never ran wrote no payload tostdout), whilestdoutstays payload until the call has failed. Such a device now refuses withUNSUPPORTED_OPERATIONand a hint naming the substitute, and the exportedreadAndroidClipboardWithAdb/writeAndroidClipboardWithAdbhelpers reject instead of resolving an empty string or nothing at all (#2674). -
Fixed (limrun):
screenshoton Limrun iOS direct sessions writes a PNG. Limrun serves its capture as JPEG and the interactor wrote those bytes straight to the.pngpath, so every capture failed downstream with "Screenshot file is not a valid PNG". The bytes are now sniffed and a JPEG is transcoded to PNG before it is written; a PNG passes through unchanged. -
Changed (ios):
open --device-hub, thedeviceHuboption ofclient.apps.open(), and thedeviceHubconfig-file key are gone. The option has had no effect since 0.20.9:opensurfaces the standalone Simulator app after a cold boot either way. Each form is now handled like any other unknown flag, option, or config key; drop it from scripts andagent-device.json(#2798). -
Changed (ios): a regular
snapshot --depth Non the XCTest runner is a presentation cut over a full acquisition, not a bound on the walk. Acquisition publishes the frames the platform reported, one normalization pass turns geometry into the app's orientation space and recomputeshittable, and the visibility fold and depth cut run on that array. Presented trees are unchanged on the screens measured; a boundary container under--depth Nnow carries its scroll hints from its real children. The runner's regular-depth capability ispresentation-cut(waspresented-frontier), and everyCGRectbecomes aSnapshotRectthrough one initializer (#2661). -
Fixed (daemon):
closenow stops an active app-log stream (and audio probe / perf capture / recording) on an implicitly cwd-scoped session. Teardown addressed those resources bysession.name(default) instead of the store address (cwd:<hash>:default), so the record read as missing, thelog streamchild leaked, and the nextlogs starton that device failed with "has not reached a confirmed terminal state" (#2647). -
Fixed (ios): Simulator AX bridge snapshots report
enabled. The bridge requested no state attribute, so a disabled control — a React NativePressablewithdisabled, for example — read as a plain button while the XCTest runner answered the same screen withenabled: false. The bridge now reads the element's accessibility traits (sent as a decimal string, since the word has bits past 2^53) and derivesenabledfromUIAccessibilityTraitNotEnabled. Source versionagent-device-simulator-ax-v1.6.0rebuilds the cached bridge on first use. -
Changed (ios): a node the source declares disabled is presented
hittable: falseeven when the capture has no hittability evidence, so on the Simulator bridge a disabled control stops counting as an interactive node and as a Maestro atomic-dispatch candidate. The navigation title affordance (a disabled title field presented as an enabled Button for the whole row) no longer carries the field'shittable: false; on the XCTest runner path that Button now counts as interactive and becomes a Maestro atomic-dispatch candidate where it was excluded before. -
Fixed (ios): a landscape iPhone snapshot reports the system keyboard's rects in the app's own orientation space. iOS hosts
UIRemoteKeyboardWindowin the device's native portrait space, so its whole subtree arrived quarter-turned — a key measured 45 pt wide and 72 pt tall atx 154in an 874 x 402 app, drawing a strip down the left edge where the screenshot shows a 724 x 204 band docked aty 198. Rules that read those numbers refused app content the keyboard was nowhere near and let a tap land on a key. The Apple runner now reads the app's interface orientation at capture time and publishes every rect under a turned surface host in the app's space, using the exact inverse of the rotation its synthesized touches already rotate through, so a reported rect and a performed tap cannot disagree about which pixel is which. The Simulator AX bridge reader has no interface orientation in its attribute set, so it refuses a capture holding a surface host reporting the app box quarter-turned —Simulator AX snapshot unavailable (window-coordinate-space-unresolved); used XCTest for this capture, which reports captured geometry in the app's own orientation space.— and the route sends that one capture to the runner instead of retiring the app generation, so the next capture of a healthy app still uses the bridge. One table proves both languages apply one rule:contracts/fixtures/window-coordinate-space.json(#2612). -
Changed (ios): the rotation table and the coordinate-space rule moved from the XCTest runner bundle into the
AgentDeviceSnapshotPresentationpackage, whereswift testreplays the golden table without a simulator. No behaviour change. -
Added (limrun):
longpresson Limrun iOS direct sessions. The interactor refused it as unsupported although the SDK exposes the HID primitives; it now holds one touch as aperformActionsbatch oftouchDown,wait,touchUp, defaulting to the 800 ms the Android and Linux interactors use when no duration is given. -
Fixed (limrun):
press --double-tapon Limrun iOS direct sessions sends both taps in oneperformActionsbatch with an 80 ms on-device pause. The interactor issued two independenttaprequests, so a network round trip sat between the taps and iOS recognized them as two slow single taps. -
Added (ios):
typeandfillwork in the Apple Pay sheet on iOS Simulator instead of failing withTEXT_INPUT_NOT_FOCUSED.com.apple.PassbookUIServiceis served in place like the web sign-in host (#2438). -
Changed (ios): Simulator captures also probe for
com.apple.PassbookUIService. It can keep running after the Apple Pay sheet closes, so a later capture in that app can reportsystem-surface-host-lingeringwhile the process stays alive. -
Changed (ios): the in-place system surface disclosure now names the sheet kind. The web sign-in sentence changed from "A system web sign-in sheet is presented over the app, so this snapshot shows that sheet (hosted out of the app process)." to "This snapshot shows a system web sign-in sheet presented over the app (hosted out of the app process), not app content". The payment host says "the system Apple Pay sheet" instead.
-
Changed (android): a private adb server no longer absorbs a port its caller named. An adb request that names a server other than the one its route holds —
-P 5037in argv, orserverPortin the call's options — is now refused withmanaged-device-transport-mismatchbefore anything is dispatched, where previously a-Pin argv was rewritten onto the route's own port. A caller that asked for 5037 could read a zero exit as an answer about 5037 after the request had run on 15038. It reachescreateLocalAndroidAdbProvider(device, { serverPort }),runAndroidHostAdb(invocation, { serverPort }), and the Limrun runtime dependency's adb calls. A request that names no server, or names the one the route already holds, runs exactly as before, and ambient adb is unchanged: with no private server named, the caller's argv is what runs,-Pincluded (#2632). -
Fixed (android): a chunked
record stop(recordings over 170 s) no longer warns that screenrecord stopped before record stop at the 180 s limit. Rotation always ends every earlier chunk before stop, so the warning now fires only when the last chunk's recorder had already exited. -
Fixed (android): a snapshot helper that could not prove it released device automation no longer refuses the next command on the strength of an
adbcall. The old code read the outcome ofam force-stopas the fact it was supposed to measure, and on a loaded host that round trip can outlive its budget while the device is healthy — the shape of #2553 — so the helper process was already gone and the command still failed withAndroid automation helper is still holding device automation ownership. Ownership is read off the device now: the probe asks the device shell forpidof com.callstack.agentdevice.snapshothelperand tells it to echo a marker when nothing matched. A process id isoccupied, the bare marker isreleased, and everything else isunknown—error: closed,cannot connect to daemon,device offline, or an adb client killed by a signal before it wrote anything. A release is therefore claimed only by an answer the transport cannot produce about itself, and no exit status is trusted:adb shellanswers 0 for a device command that failed, and an adb that dies by signal leaves the executor inventing an exit code it never saw. A refusal requires two reads that both name the process, which keeps a helper still inside Android's exit path from costing a command. Scripts that match the failure reason seeandroid_snapshot_helper_runtime_occupied, which replacesandroid_snapshot_helper_retirement_unconfirmed. -
Changed (android): a snapshot helper session that reaches ready settles a release the previous teardown could not prove.
am instrumentforce-stops whatever is already instrumenting the helper package, so a session that reported itself ready is the only helper process the device has left, and the unproven release went away with the process that owed it; the next command no longer force-stops the session it has just started becausepidofhappens to be unreadable. A helper start that fails is also retried after a backoff scaled to how long it spent failing (10 s to 60 s) instead of on every command, which had roughly doubled command time on hosts where the helper never starts. And the wait for a started helper to announce itself no longer uses a fixed 10 s: it takes half of the helper-command budget the capture was built with, 15 s today, which is what had been pushing devices slower than a capture off the persistent path. On a host where the helper took 12 s to announce itself, the command used to answer with the one-shot transport and now answers from the session. The CLI's--timeoutreaches that wait as its deadline aborting it, not as the number. -
Fixed: an iOS snapshot whose XCTest query-sweep tier cannot read the screen no longer ends the runner process. On a live React Native feed (Bluesky Home, images re-rendering) the AX server rejects each of the sweep's 19 element-type queries with
kAXErrorIllegalArgument, and XCTest records every rejection as a test failure wordedFailed to resolve query: .... The runner muted the siblingFailed to get matching snapshot: ... kAXError...wording and not this one, and XCTest ends the test case as soon as the main-thread block that recorded an unmuted failure returns, so the runner died right after (or in the middle of) every hostile snapshot and the next command paid a fullxcodebuildboot. Both wordings are now muted when they carry an AX server code; the timeout andApplication X is not runningvariants keep recording. The sweep also no longer runs behind an abandoned read: every bounded main-thread dispatch that outlives its slice now counts as occupying the main thread (one counter, where the tree XPC and the system-modal probe used a second one of their own), so once the tree tier's viewport read grinds past its 1 s slice the plan goes straight to private AX and answers instead of queueing the sweep, the post-snapshot mark, and its own bookkeeping behind seconds of main-thread work. A capture that fails outright while that work is still grinding queues its cached-target drop behind it instead of waiting a second for it, and a fresh process's first capture is no longer penalized by the tree slice timeout, which had bypassed the warmup exemption every other penalty honors. The per-bundle penalty and accepted-depth memory that make later captures of the same screen cheap now survive, because the runner does. -
Changed (android): the snapshot helper release manifest no longer carries
installArgs, and the helper installs with a fixedadb install -rlike the IME helper. The array only ever spelledinstall -rplus the-tthat #2603 retired with thetestOnlyflag, so the manifest → flag → option → flag round trip and its allowlist carried nothing. Older manifests that still contain the field parse unchanged; the field is ignored. The adb providerinstallcapability now takes onlyreplace(#2364). -
Changed (android, harmonyos): every
adb shell,adb exec-out, andhdc shellcommand now goes through one device-shell funnel that renders each argument for the quoting its transport applies (#2026, #2611). The device shell re-parses the arguments it is handed, so an unquoted dynamic value was a command injection: Android quoted a few sites by hand and HarmonyOS quoted none. The two transports do not quote alike, which is why a caller names the transport ('adb'or'hdc') rather than choosing quoting.adbescapes nothing, so a word reaches the device inside whatever quotes it is given.hdcwraps every element it forwards in double quotes, where a single quote is inert while$, a backquote, and"stay live: on a nova 14,filltext containing$(id)came back as the device's ownidoutput and a"in the text ended its argument, so words on that transport are escaped instead of wrapped. Four effects are visible on a device. HarmonyOStypeandfilltext now reachesuitest uiInput inputTextbyte-identical, confirmed with a payload carrying quotes, a command substitution, a pipe, and a redirection. On Android an empty argument renders as''rather than vanishing from the command, so a command that read its own shift and its operand as two words no longer misaligns; HDC drops an empty element on the way to the device and cannot carry one, so it is refused withdetails.reasonhdc-empty-word-unsupported, as is a script fragment, which could only arrive there as literal text. A script body handed tosh -con the adb transport arrives as one argument. Custom adb executors and providers (SDK, MCP, and relay transports such as Limrun's) that pass a raw['shell', …]or['exec-out', …]argv are now refused withINVALID_ARGSanddetails.reasonunguarded-device-shell-argv, because a command the transport is about to let the device parse has to be one the funnel built. Build it withrunAndroidShell/runAndroidExecOut(aDeviceInfo) orrunAdbShell/runAdbExecOut(anAndroidAdbExecutor), all exported fromagent-device/android-adb, and pass each dynamic value as its own word. SDK:AndroidAdbExecutorandAndroidAdbProvider.execnow receivereadonly string[], so a custom executor annotated(args: string[])must widen its parameter to take the command. -
Fixed: BrowserStack sessions honour
--provider-project,--provider-build, and--provider-session-name. The capability builder emitted the legacy JSON Wire keysdevice,os_version, andappat the top level next to the W3Cbstack:optionsblock; the hub treats a request carrying any legacy key as a legacy session, reads the labels from the legacy top-levelproject/build/name(never set), and ignoresbstack:options, so every session landed in "Untitled Project" / "Untitled Build" with an empty name — even after #2495 carried the flags to the provider (#2494). The builder now emitsappium:deviceName,appium:platformVersion, andappium:appand no legacy key, verified against live App Automate sessions. -
Added:
--provider-appium-version <version>(alias--appium-version) pins the Appium server BrowserStack runs for the session, asbstack:options.appiumVersion. Unset, BrowserStack falls back to Appium 1.x, which predates themobile:commands the interactor issues (deepLink,pressButton,activateApp). -
Changed (iOS runner): what recovers a stuck runner is decided by the recorded error, not by its wording. A readiness preflight marks the error it gives up with, and that marker is now the whole test for restarting the session and replaying the command — except for a request that was canceled, which that same catch also marks: a command nobody is going to send again has no restart to spend, and the session it would tear down may be one that still works. Two message checks decided it before, and a preflight reaches the caller in whatever shape its connect loop ended with — "Runner did not accept connection", "Runner endpoint probe failed", a killed
simctlfallback, a post that ran out of its budget — so only some of those restarted and the rest failed the command. The other half is what no longer happens: when a slow boot spends the whole prepare budget, the health check reports "prepare ios-runner timed out", and that no longer wipes a restoredxcodebuildartifact on the way to a rebuild — the runner session is invalidated and prepare retries with the artifact intact. Only a failure that indicts the artifact rebuilds it, so a runner that refuses the connection or never answers on any route still wipes it and rebuilds, which is what that rule is for. -
Added (record):
record stopnow answers the question a video cannot — whether its recorder actually stopped — beside the export. The result carriesrecorderandnativePathDispositionon CLI--json, the Node client, and MCP (ADR 0024). Today a stop saysconfirmed, orlostwithowner-session-lostfor an Apple recording whose session was invalidated, and names its artifact pathretirableorretired; the wider vocabulary those two fields declare (unconfirmed, the identity-mismatch reasons,pending) arrives with the later ADR 0024 steps that gain the probes those states describe. Both are disclosures about the recorder and the path it writes to, not failures: the export is served either way, and a stop with nothing to report — an older session's replay, or a backend whose recorder writes the served file itself — omits them. No stop changes outcome in this release; the fields land first so the coordinator can report what it already knows before it starts acting on it. -
Fixed (record): an Android stop credits the device with retiring its recording only when the device proved the chunks gone. The probe read any failed
test -eas "not there", so an adb that timed out or a device dropped mid-call turned chunks that were still on the device intonativePathDisposition: "retired", and a reattach that could not question the device at all declared the recording's artifact lost. A probe that never ran now answers uncertain: the path staysretirableand the recording stays finishable until the device answers. -
Changed (record): an iOS Simulator recording no longer has the recorder write the file the caller asked for.
simctlrecords to a<name>.native.<ext>sibling;record stopcopies that file to a<name>.collected.<ext>sibling, checks that the copy has an MP4 container, writes the caller's--outpath once from the copy, checks that export is a playable video, and retires the recorder's own file (ADR 0024 2.3). An export the finalizer refuses is removed, so--outonly ever holds a video that passed that check. The caller's path is never a file a recorder is still writing, and a stop that fails before the export exists leaves it absent with the copy in place — so the next stop resumes from the copy instead of signalling a recorder that already stopped. Both siblings are deleted on success, and a stop that got that far answersnativePathDisposition: retiredrather than theretirableit had to answer while the recorder's file and the served file were one file. A recording whose stop fails and is then abandoned (session close, daemon restart, forced cleanup) keeps its video in these siblings beside--out, where the recorder used to leave it at--outitself; they are the only copy of that video, so nothing deletes them. -
Changed (record): an Android recording is no longer pulled onto the path the caller asked for.
record stoppulls the device's chunks to<name>.collected.<ext>siblings, retrying each pull until it plays, then writes the caller's paths from copies of them and drops the collected set once the finalization is journaled (ADR 0024 2.3). Chunk paths the finalizer refused are removed. A stop that dies before the export exists leaves it absent with the pulled set in place, and the next stop resumes from that set instead of signalling ascreenrecordprocess that already stopped and pulling a file that may have moved since. The 180s platform-limit disclosure now travels with the recorder's own observation rather than with the export, so a stop that has to be driven again still says it; every disclosure is still in the onewarning. A retried stop serves every chunk and thecapturedDurationMsits first attempt finalized, and measures the idle tail against the instant that attempt signalled the recorder rather than the time of the retry. A stop that fails and is then abandoned keeps the pulled set on the host beside--out. Chunk paths and--client-output-pathnaming are unchanged. -
Fixed: a process lock that could not be given back no longer waits for the daemon to restart. A release that cannot verify ownership — a refused
unlink, an unreadable record — left its record standing and naming the live daemon, and the next acquire read that as a live owner and timed out after 30 s on every runner build or launch until the process restarted. The claim inside is spent the moment the release is asked for, so a reclaim here now reads it as dead and takes the path back, and the failed release is recorded in the request log asprocess_lock_release_unverified. A record is only read that way when this loading of the lock code issued it: a second bundled copy of the module in the same process shares the pid and cannot have a live claim cleared under it. -
Changed (lock errors): code that takes a process lock now answers one question in one helper, which of its two failures the caller hears. The work inside the lock outranks a lock that could not be handed back, so a build or a publish that failed keeps its own error instead of being replaced by
Timed out waiting for …, and work that succeeded still reports the lock it could not give back. The Apple runner's artifact, cache, lease and disposal paths, the managed-allocation store, the device-claim store, the iOS snapshot bridge cache, the Swift recording cache and the agent-browser setup moved onto it, replacing hand-written try/catch pairs that each chose differently. -
Fixed: the redirect of
~/Library/Developer/XCTestDevicesgives itself back in one order — restore the host's own device set, then release the lock — and a restore that was refused is what the caller is told, whichever give-back door a teardown used. The lock's own complaint used to replace it in afinallyand the best-effort door then dropped it, leaving the symlink pointed at the agent-device simulator set with nothing said about why. A simulator whose set already isXCTestDevicesis no longer failed by a lock it could not verify, either. A leftover from an interrupted build — the host's set renamed aside andXCTestDevicessymlinked into a simulator's own set — is now put back before the redirect decides whether it is needed, so the first build after an interruption still gets its own device set instead of the host's. A redirect that could not be installed reports the restore that failed with it, and names a backup path only when that backup is really on disk. -
Changed (sessions): the implicit session is now keyed by workspace and platform, so one checkout
can drive iOS and Android without inventing a
--sessionname for every command (#2580). An implicit session was addressed bycwd:<workspace>:default, one slot per checkout, and it stayed bound to the first device it touched. A repo that tests both platforms — a visual-regression run acrossreact-native-papercomponents, for example — could not open the second one at all: afteropen --platform ios,open --platform androidfrom the same directory failed withINVALID_ARGS("already bound to apple device "iPhone 17""), and so didboot --platform android, which binds nothing and only needed a device to start. The hint was correct (--session androidworks), but following it means threading a hand-written name through every command of both legs, and a script that drops one flag silently talks to the other platform's device.--platformnow selects the implicit session, so the platform a script already declares is the only handle it needs:cwd:<workspace>:iosandcwd:<workspace>:androidcoexist, each with its own device, app, and artifact directory. Three rules keep the behavior that was already earned.- A platform-naming request joins the workspace's session only when it genuinely agrees with it,
so a session opened without
--platform— which keeps the platform-lessdefaultleaf — stays reachable from commands that do name a platform and keeps writing to its own artifact directory instead of growing a twin beside it. A request that agrees on platform but names a different device or target still gets the existingINVALID_ARGSrefusal; it does not silently fork a second same-platform session that one--platformwould then have to disambiguate. - A request naming no platform joins the workspace's only implicit session — what every
single-platform script does today, so those are unaffected — and refuses with
AMBIGUOUS_MATCHwhen the workspace holds several, naming every address and the--platform/--sessionflag that selects it, instead of choosing a platform by open order. Same for a broad selector such as--platform applethat matches both this workspace's iPhone and its Mac. - Inventory commands —
session list,devices,doctor,capabilities,apps, which the registry classifies assessionKind: 'inventory'— never claim a session and keep resolving an address through the ambiguity. Refusing those would refuse the command an agent runs to resolve it.eventsandcloseare deliberately not in that set: each reads or tears down one session, and a silently-emptyeventsor aclosethat closed nothing would be worse than the refusal. Two adjacent repairs were required. A settling interaction published the live session underSessionState.name, which for an implicit session is onlydefaultand not the address it answers to, soagent-device session listalready reported a phantom second row beside the real session; under platform keying that phantom would also have read as a second session the caller has to disambiguate, so the publisher now stores under the key the store itself owns, and workspace-session counting collapses one session reachable under two addresses regardless of writer. And--session-lock's platform reachesflagsonly after routing has chosen the key, so routing now readsmeta.lockPlatformtoo — otherwise a lock-policy caller, the exact audience that avoids naming sessions, would land on the wrong leaf. Explicit--session <name>is untouched and still addresses one session verbatim.
- A platform-naming request joins the workspace's session only when it genuinely agrees with it,
so a session opened without
-
Fixed: a
record stopthat could not produce its export no longer destroys what its own retry reads back (#2591). The shared coordinator compensated every failed finish by force-cleaning the resource, which on Android deleted the device-side MP4 and the native manifest the hint just told you to re-pull: the secondrecord stophad nothing left to collect and the recording was gone. Each durable kind now declares what its retry needs.screen-recordingandperf-capturepreserve, so a failed stop keeps the device artifact, keeps the manifestopen, returns its own error, and the nextrecord stopin that session exports it — proven on an emulator whoseadb pullfailed its first attempts and then exported the 90 KB the first stop left on the device.app-logandaudio-probesaydispose-on-failed-finishthemselves, because their retries re-read a log file and a status file that cleanup never touches. A finish also states why it was asked for:capturemay preserve, whiledisposal— session teardown, the one caller that owns forced cleanup — disposes whatever a failed finish left. Two Apple paths had to become genuinely retryable for that to be true: the runner path memoized its refused stop and handed the same rejection to every laterrecord stopwithout asking the runner again, and the simulator path rejected a recording purely becausesimctl recordVideohad exited non-zero — discarding a video the recorder had already written and leaving an exit code no retry could change. A stopped recorder is now an observation rather than a failure: the exit is disclosed on the completion and the file is collected, so those recordings export instead of erroring. Expect one trade: while a preserved recording is open,record starton that device is refused until its session runsrecord stopor closes. A simulator recording no retry can rescue now names the exit that made it unreadable —simctl recordVideo exited with code 1,was killed by SIGKILL, plus the recorder's stderr — drops its retriable flag, and points at closing the session, while a recorder still finalizing its file keeps the retry hint.perf stopno longer memoizes a refused finish, so its second attempt re-pulls the trace the first one preserved. -
Changed:
record stopno longer carries a start-trim step no recorder could arm. The trim cut the interval between recorder start and target-app readiness, but the runner'srecordStartanswer has never carried either timing and the simulator path supplies none, so every built-in recording took the untrimmed branch while the packaged Swift trimmer, its contract fields, and the telemetry timestamp shifting stayed shipped with it. Gesture telemetry now carries the timestamps it recorded; recorded videos are byte-for-byte the videos those paths already produced. Overlay burn-in, output stability checks, and the recorder-start gesture-clock anchor are unchanged (#2584). -
Fixed: an iOS capture that no backend could read now says which backend was asked and what was on screen, instead of failing on the internal
regular iOS snapshot presentation requires a valid viewportinvariant alone (#2560). The runner declares such a payload sparse — backend, reason code, and its own reason — and the daemon read that verdict, then discarded it while reconstructing a viewport from a synthetic root that has none. Asnapshot --actionscapture of a web sign-in sheet therefore reported a viewport problem and named neither the private-AX backend that cannot read an out-of-process surface nor the surface presented over the app. The verdict now travels with the refusal aserror.details.snapshotQuality, and the hint composes the shared sparse-capture advice with the bundle id of the surface host when one is presented. Onreplayandtestthe verdict now survives into theREPLAY_DIVERGENCEdetails, which carried only four cause keys before. Captures that used to succeed are untouched: a sparse payload whose tree presentation can still serve presents exactly as before, and a payload the runner did not declare sparse keeps the plain invariant byte for byte. -
Fixed: skipped
optional: trueMaestro steps are no longer invisible on the human surface (#2560). The warning a skip leaves now travels with the run whether it later passes or fails:replayprints aWarning:line after its summary and repeats the run's warnings after a failed run's error,testprints aWarnings:section after the suite summary naming each test, and a failed test result gained thewarningsarray the passing result already had, so--jsonand JUnit carry the skipped steps of a failing test too. -
Fixed: an Apple runner presentation refusal now carries the registry identity of the system surface the tree was acquired from as
error.details.systemSurface(#2560). Previously a selector-backed command failing at the capture boundary underoptional: truegave nothing naming that boundary — the web sign-in sheet out ofSafariViewServicewas invisible in the error, and the miss looked like a selector problem inside the app. The sparse-declared case already names the surface host in its hint via #2572; this covers the provenance everywhere the runner reports one. -
Changed: a capture that a backend cut at one of its limits now says so in the snapshot's warnings, on every platform, instead of only setting
truncated: truein JSON. The text path had no disclosure at all, so an agent read a screen missing its footer, tab bar, or the items after a long list as complete — the backends walk the tree in document order, so what falls off is what comes last, on screen or not. One shared warning renders from the shared flag; the limit and dimension stay backend-side. The depth-cap warning no longer suggests--scopeas a way to read deeper: on iOS, scope narrows the presented view and acquisition stays scope-blind. -
Changed: the iOS Simulator AX bridge caps a capture at 5000 nodes, up from 1500, the Android helper's bound. Measured on a synthetic 600-row screen, acquisition time did not move with the cap (the native read fetches the whole tree; the cap only stops conversion) while the 1500 cut dropped the screen's on-screen footer.
-
Fixed: Android snapshots carry the accessibility
selectedstate an app sets on a control, sois selected, aselected=trueselector, and a Maestroselected:qualifier work on Android (#2462). The helper never serialized the attribute, and the host reads only the helper's XML, so no later layer could recover it:get attrshad noselectedfield, no snapshot node was marked selected, and the same assertion that passed on iOS failed on Android with "Maestro visible condition did not match" for an element that is visible — whileselected: falsematched every Android node. The helper now emits both answers, likeenabledandpassword, so an unselected control answersfalseand a helper older than the attribute answers nothing; the host parser, the Android hierarchy node, and the published snapshot node carry it through toget attrsand the[selected]marker in snapshot text. Snapshot lines now render that marker whenever selection is rendered, not only when text surfaces are summarized:--settleanddiffalready compared selection, and a line that compares a fact it cannot display turns a tab tap into a changed pair whose two lines look identical. -
Fixed: Replay test artifacts with colliding filenames retain distinct copies without overwriting other diagnostics, replay sources, timing traces, or attempt manifests.
-
Fixed: Custom test reporters reject invalid exit codes, including values such as
256that could wrap to success and hide a failing suite.getExitCodeaccepts integers from0to255orundefined; JSON output reports an invalid code as oneINVALID_ARGSerror. -
Fixed: Android
record startno longer refuses to begin after a reused emulator reassigned the previous recorder's pid. A completed recording's native marker is retired only once its recorder is proven gone, but only an absent pid counted as proof — a pid that now names an unrelated process, or a recorder that exited and waits to be reaped, did not.record startthen failed every later attempt withAndroid screenrecord completed evidence cannot be safely retired, andrecord stopcould not return an already-finalized recording. Proven termination now retires the marker and returns the stored completion; a live or unreadable recorder still blocks, and the unrelated process is never signalled. A reused pid that runs a replacementscreenrecordon the same remote path proves the old recorder gone but not that the path is free, so that marker and artifact are retained until the replacement ends, and neither is signalled (#2476). -
Fixed: Android
record startno longer refuses forever on an emulator re-adopted under a new serial. The device-side marker records the device identity that wrote it and a later start retired it only when that identity matched, so a marker left by an earlier session on the same AVD blocked every recording on the re-adopted device withAndroid screenrecord native recovery evidence already exists— reported as an internal error whose hint asked for a bug report — whilerecord stopanswered that no recording was active and no session could reach the marker, because recovery always binds the device identity its own record names. A marker now retires when its recording is terminal or when it names a device identity this transport can no longer address, and only once every recorder it names has provably released its artifact; an interrupted launch commits no recorder identity, so its artifact is checked against the recorders running on the device first. A recorder that is still writing is left alone:record startrefuses withDEVICE_IN_USEanddetails.writernaming whether the marker's own recorder or another one holds the path, and only the unmanaged one ends on its own at Android's 180 second limit. A device that cannot answer that question — an unreadable process table, or a candidate process whose identity cannot be read — is refused rather than assumed free, even when other recorders writing that path were identified, so an artifact is never removed under a recorder the probe failed to see. What still refuses — unreadable or undecodable evidence, a marker the other transport mode wrote, and an open recording this device identity still owns — is now a typed error naming the marker path and the command that clears it,record stop --session <name>or removing the marker once no session owns it, instead ofUNKNOWN(#2550). -
Fixed: a polling
waitno longer surrenders its whole budget the first time the iOS runner answersRUNNER_BUSY. That code means an earlier command exceeded the runner's execution watchdog and its abandoned main-thread work is still draining, which clears on its own, so await text ... 20000could fail in under a second with a failure the runner itself asked the caller to retry. A poll refused with a failure its producer marked retriable is now ridden out like an unreadable capture: the wait keeps polling to its deadline, records the poll asretriablein its timeout evidence, and surfaces the refusal only if no readable capture ever completed. That surfaced refusal keeps the producer's code, message and retry details and now also carries the wait's owncaptures,readableCaptures,waitedMsandpolls, so a budget spent entirely on refusals is distinguishable from one immediate refusal. A wedged runner (RUNNER_WEDGED) is not retriable and still ends the wait at once. -
Fixed: a runner failure recovered from the lifecycle journal after its transport response was lost is now classified exactly like the same failure on a live response.
RUNNER_BUSYreached callers as a bareRUNNER_BUSYwire code without theretriableflag on that path, while the live path published it asCOMMAND_FAILEDwithdetails.runnerErrorCodeandretriable: true; both paths now read the runner's code through one classifier. -
Fixed: iOS Simulator snapshots of Safari and of apps with a
WKWebViewstopped showing the page in 0.21.0 — chrome plus empty[webview]nodes, no links, text, or form fields, so no ref could reach the page (#2484). The host AX bridge that 0.21.0 made the Simulator's snapshot source reads one process, and WebKit content lives in another; the bridge delivered the boundary as anAXRemoteElementleaf and the tree was published as if that were the screen. The source now refuses a tree whose on-screen web view ends at that leaf (remote-content-boundary) and the route serves XCTest, which resolves remote elements, for the rest of that app generation — the same path 0.20.x used. The snapshot discloses the switch through its warning, and a relaunch re-enables the bridge. -
Fixed:
testexpands relative globs from the caller's literal working directory, so directory names containing glob characters no longer cause missing suites or select a different directory. Missing non-glob inputs also retain their not-found error in these directories. -
Fixed: JUnit reports remain readable when replay results contain characters forbidden by XML 1.0, replacing them with U+FFFD while preserving legal Unicode and whitespace. Original suite values remain available in JSON and other reporters.
-
Fixed:
replay exportpreserves deep links without//, includingtel:andmailto:, as MaestroopenLinkcommands in both standalone and app-plus-linkopenactions. -
Changed: a command whose synopsis is generated names each option with the label its declaration carries, so
snapshotnow shows--depth, -d <depth>and--scope, -s <scope>where it used to show the short aliases, and--recordis documented underCommand flags:instead of inside thesnapshotandissynopsis lines.snapshot,proxy,daemon,device,doctor,prepareandtv-remoteno longer restate their option list in a hand-written usage string, so adding an option to those commands updates--helpon its own (#2444). -
Fixed: iOS
--depthonsnapshot,is,wait,get, andfindno longer fails withregular iOS snapshot presentation requires a valid viewportwhen the runner plan is pinned or deferred to the private AX backend (custom actions, a private AX verdict on the session, or the XCTest channel penalty). The runner refused a regular depth-capped request on every backend but the recursive tree, fell through to its synthetic sparse root, and the daemon rejected that root as a missing viewport. Presentation applies the presented-depth cut to whatever hierarchy a backend acquired, so every backend serves the request; the private AX declaration is nowregular-depth=presentation-cutand an acquisition that stopped short of the cut keeps disclosing that throughtruncated/effectiveDepthas it does unscoped. -
Fixed: repeated unfiltered Android snapshots stay compact when identical element bounds arrive with a different property order. Changes to the bounds still re-emit the tree.
-
Fixed: iOS
network dumpno longer omits requests that reused a keep-alive connection. CFNetwork logs a request URL only on the line that opens a connection, so a second request to the same host produced nourl:line and was dropped from the dump entirely — an "this endpoint was called" check read as a definite fail. Such a request is now reported against the origin its connection was opened for, withpathUnavailableset, its status, and its timing. A reused request whose connection was opened before the scanned window cannot be named at all; those are counted in the dump'sunnamedRequests, so an empty result still reports that traffic was observed. The identities behind that count reconcile the app-log and recovery windows internally — so overlapping traffic is not double-counted and disjoint traffic is not under-reported — but the response carries only the count, which stays bounded however large the scan window was. The notes say absence of an endpoint does not prove it was not called. -
Fixed: a URL logged as a delimited
url: <value>,field no longer keeps the separator the log format put after it, so an entry'surlcompares equal to the endpoint under test. A bare URL elsewhere is left alone, since nothing there establishes that trailing punctuation is not part of the path. -
Added:
replay exportsupports flows that switch apps and return, preserving eachopen <appId>target as an explicit MaestrolaunchApp.appId. -
Added:
replay exportconverts recordedhomeactions to MaestropressKey: Home, allowing app-to-home-to-app journeys to be exported. -
Added: polling
waittimeouts (wait <selector>,wait text,wait @ref, andwait absentafter a readable capture) carry a per-poll timeline inerror.details(captures,polls[]withstartedMs,durationMs, and a typedoutcome: readable, unreadable, deadline, runner-restart) next to the unchangedreason, so a failure says where its budget went without opening the request log. Long waits keep the first five and last twenty-five polls. The replay landmark-mismatch refusal carries the same poll evidence next to its mismatch details;wait --stabletimeouts and a never-readable strict absence keep their existing diagnostics. -
Fixed: Android
orientationnow returns once the display reports the requested rotation (pollingdumpsys display, up to 15s) instead of right after writing the settings. On a loaded emulator the rotation takes seconds, during which accessibility reads hang, so the next command paid for the transition; awaitissued right afterorientationcould spend its whole budget there. A display that never reaches the requested rotation now fails the command with the observed rotation instead of reporting success; a display that reports no rotation is left to the setting as before. -
Fixed: the iOS Simulator AX snapshot route bounds how long a capture waits for app discovery and stops starting a discovery per capture. Discovery (
simctl launchctl listthrough xcrun) takes seconds on a loaded host; a capture now waits at most 1.5s for the one in-flight discovery, takes the XCTest fallback, and the discovery keeps running under its own 15s deadline for the captures that follow. Previously each capture ran its own probe with a 3s timeout on its critical path, so awaitissued right afteropencould spend its budget on probe timeouts and reportwait_capture_stalledwith the app already on screen. -
Fixed: iOS snapshots no longer report
truncated: truemerely because a later backend produced them. The runner stamped every recovered capture as truncated — including a complete private-AX tree taken while the XCTest channel was penalized as slow — so a strictis absent/wait absentrefused it with "capture was truncated" on loaded CI hosts.truncatednow tracks completeness only: payload truncation, a depth-limited capture, or a sparse terminal payload. -
Fixed: Android
alert accept/alert dismissreturn only once the dialog has left the accessibility tree (a different alert taking its place counts as dismissed), matching the iOS runner's re-check. Previously they returned right after the button press, so the next read could still see only the dialog window. A dialog that stays visible past the action budget now fails withalert <action> did not dismiss the visible alert. -
Added strict
wait absent <selector> [timeoutMs]polling for zero selector matches. Incomplete, sparse, truncated, scoped, depth-limited, and Android unreadable captures cannot prove absence; deadline diagnostics retain typed capture evidence and stable first-match details (#2236). -
Added: the device-claim store can hold an allocator-held claim (schema v3) for a device an allocator-managed pool owns. It has no owning process, so
device statuslists it in the normal view (never as stale),device release --stalerefuses it withallocator-held-owner, the daemon-startup sweep and session close leave it alone, and a command that binds the device ordinarily is refusedDEVICE_IN_USE/DEVICE_CLAIM_ALLOCATOR_HELD. Process-owned claim files are unchanged at schema v2. Two notes for mixed installations: a daemon older than this release reads a v3 file as an unreadable claim record and fails closed rather than clearing it, anddevicesreports noclaimedByfor such a device until the managed-inventory filter lands. -
Added the
harmonyos-instancelease contract and CLI/runtime plumbing as a prerequisite for HarmonyOS proxy support; provider/daemon allocation remains gated until its end-to-end lifecycle is implemented and validated (#2266). -
Fixed:
settings airplane on|offnow takes an Android device offline. It is applied through the connectivity service (cmd connectivity airplane-mode), which drives the radios, instead of writingairplane_mode_onand broadcastingACTION_AIRPLANE_MODE_CHANGED— a broadcast Android refuses for non-system callers, so the old path failed after writing the setting and left the device reporting airplane mode with the network still up (#2223). The response now reports theairplaneModethe connectivity service holds after the change, and an Android build that does not expose that command is refused withUNSUPPORTED_OPERATIONbefore anything is written. -
Fixed: the MCP registry entry (
server.json) now declares the fixedmcpsubcommand viapackageArguments, so a registry-format launcher — the MCP Registry or the website's/.well-known/mcp.jsondiscovery manifest — starts the stdio MCP server. Previously it ranagent-devicewith no subcommand, i.e. the bare CLI (#2275). -
Breaking (0.21): iOS Appium/WebDriver snapshots now expose engine-owned acquisition facts and typed fidelity warnings. The SDK snapshot
truncatedfield is optional when Appium cannot report hierarchy completeness; regular snapshots fail closed without valid viewport evidence, whilesnapshot --rawremains available for diagnostics (#2195). -
Security (daemon, remote/proxy HTTP only): when
AGENT_DEVICE_HTTP_AUTH_HOOKis configured and a request's hook result does not attest atenantId, the request is now refused (401) outright — the daemon no longer runs it as whichever tenant the client declared (RPC bodymeta.tenantIdorflags.tenant, or thex-agent-device-tenantheader on the upload/artifact-download/diagnostics routes) and no longer admits it unscoped when the client declares nothing either. This closes both a shared-token impersonation path and an unscoped-access path to tenant-owned sessions/artifacts in multi-tenant deployments. Deployments with no hook configured (the local loopback CLI) are unaffected. A hook must attesttenantIdon every request it wants the daemon to admit. -
Breaking (0.21): removed aggregate performance compatibility (
perf,perf sample,perf metrics, themetricsalias, optionlessclient.observability.perf(), and SDKarea: 'metrics'). Useperf frames,perf memory sample,perf cpu profile start|stop|report, orperf trace start|stop; removed CLI and raw daemon forms fail with this migration guidance. -
Breaking (0.21): removed legacy batch JSON steps with
positionals/flags. Use{"command":"...","input":{...}}; rejected steps now include a concrete structured example. -
Breaking (0.21): removed the deprecated Node client
command.rotatewrapper and itsRotateCommandOptions/RotateCommandResultexports. Usecommand.orientation; the already-removed CLIrotateform keeps its targeted migration error. -
Security (MCP/AI-SDK tool surface): the operator-owned endpoint and path inputs —
daemonBaseUrl, the MetroproxyBaseUrl,stateDir,cwd,iosSimulatorDeviceSet,iosXctestrunFile,iosXctestDerivedDataPath,iosXctestEnvDir— follow the credential inputs off the model-writable tool surface: no longer advertised, refused as explicit input with guidance, and resolved from env/config only (a model-writabledaemonBaseUrl/proxyBaseUrlwould redirect the env-resolved token to an arbitrary server). Dropping these plus the credential fields shrinkstools/listby roughly half. CLI flags and the SDK client options are unchanged. -
MCP tool descriptions now declare their enforced client timeout envelope (90s default, 180s install, 300s+ lease allocation, unbounded only for the streaming
testrunner), sourced from the descriptor registry's timeout policy so the declared number cannot drift from the enforced one. -
Security (MCP/AI-SDK tool surface): the shared command-tool executor now enforces the advertised tool schema as an admission boundary — every raw
tools/callargument must appear in the tool's advertised (additionalProperties: false) schema, or it is refused before config/env resolution. Hiding a key fromtools/listalone was insufficient: the router forwards raw arguments verbatim and the MCP config resolver readconfig/remoteConfigas CLI flags, so a model-supplied config file could loaddaemonBaseUrl/daemonAuthTokenand redirect the operator's token to an arbitrary endpoint. Deny-by-default closes that, the operator keys, and any unknown key at once; operator env/config defaults still resolve (they never arrive as tool input). Retired keys are still admitted so their migration guidance answers. -
Security (MCP/AI-SDK tool surface):
daemonAuthTokenand the MetrobearerTokenare no longer advertised as tool input properties, and an explicit value is refused with guidance instead of being forwarded. Credentials are operator-owned: setAGENT_DEVICE_DAEMON_AUTH_TOKEN(ordaemonAuthTokenin~/.agent-device/config.json) andAGENT_DEVICE_METRO_BEARER_TOKENon the process serving the tools. The model both reads untrusted app UI text and picks tool arguments, so a model-writable credential parameter was a prompt-injection exfiltration path. CLI flags (--daemon-auth-token,--bearer-token) and env/config resolution are unchanged. -
Release hygiene: after
npm publish,release:mark-devmovesmainto the next patch with a-devprerelease marker so the version onmainnever equals a published version (registry scanners diff the tool surface per version string, and a moving surface under a released number reads as a republish).release:preparerefuses to publish while the-devmarker is in place. -
Windows
--platform webworks again.agent-device web setupno longer fails withnpm not found in PATH, and every web command — includingweb doctor— no longer fails withspawn EINVAL. The managedagent-browserbackend is now launched asnode <js-entry>on every platform instead of through itsnode_modules/.binconsole shim, which is a.cmdfile on Windows thatchild_process.spawnrefuses without a shell (CVE-2024-27980 hardening);shell: truewould only trade that for argument-quoting hazards and aDEP0190warning on every command. Setup spawnsnpmfrom PATH unchanged on macOS and Linux, and runs npm's ownnpm-cli.jsunder the current Node only on Windows, where a barenpmis not spawnable. A managed install now counts as present only when the backend package itself is, andweb setup --json/web doctor --jsongainentryScriptandpackageDir; the publishedbinaryPathis unchanged and still names npm's console shim, now informational rather than the spawned command (#2022). -
Parameterized
fill --record-asprotection is now recording-session-scoped instead of fill-step-scoped (ADR 0017 amendment): a later, unrelated recorded action (wait,is,get) can no longer re-serialize an app-rendered echo of an already-parameterized value into its own result ortarget-v1identity evidence. An echoingwaitlandmark no longer qualifies as an ADR 0016 destination guard, sosession save-scriptrefuses it and directs the author to a stable landmark instead of silently publishing the secret. The protection uses one small, explicit, ephemeral, never-serialized per-session map populated only from values the author already opted to parameterize; ordinary non-parameterized recordings are unaffected (#1398). -
Android covered-state publication now has one owner: same-window surfaces remain visible for diagnosis, while the daemon marks exactly ordered covered controls non-actionable with
interactionBlocked: "covered". Helper-onlydrawing-orderstays private rather than entering the snapshot contract, sparse floating overlays remain usable, and API 23 fails conservative with the existingandroidSnapshot.occlusionScanUnavailabledisclosure (#1832). -
iOS regular
snapshot --depthnow measures depth after structural accessibility wrappers collapse. The recursive-tree backend follows a bounded presented-depth frontier, so controls that fit the requested regular depth are no longer lost behind raw wrappers; raw--depthremains a traversal-depth limit. Flat query recovery is limited to one presented level, and private AX does not claim deeper regular-depth completeness until it has a hierarchy-aware frontier (#1797). -
iOS regular snapshot nodes now publish presentation-owned effective geometry through the existing
rectfield: backend-reported frames remain available to acquisition, while regular output uses the viewport and declared scroll-clip intersection. Raw snapshots and direct element reads retain reported geometry (#1797). -
Android recording-session commands now warn when blocking-dialog readiness inspection fails open. The requested command still runs, but the successful response discloses that readiness could not be inspected and preserves the inspection error's actionable hint, including
pnpm build:androidwhen the snapshot helper is unavailable (#1895). -
Breaking (device selection): when a command needs one concrete device, carries no
--device/--udid/--serial, and more than one candidate is equally preferred, agent-device now refuses withAMBIGUOUS_MATCHand the candidate list instead of quietly picking one. Established preferences are unchanged — virtual over physical, booted over offline, and the Apple kind/target ranking — so a single booted emulator beside offline ones still resolves, an existing session binding still resolves (its identity is already fixed), and explicit selectors still resolve. What no longer happens is choosing between two equally booted devices by discovery order or alphabetically: that produced a successful response describing a device the caller never selected, and reads are no safer than writes there.devicesand other genuinely multi-device commands never enter singular resolution and are unaffected. The error carries the bounded candidate list in the declareddevicesdetails domain, so CLI and MCP print it, with a hint naming the right selector for the platform (--serialfor Android/HarmonyOS,--udidfor Apple, or--device "<name>"). -
--udidwith--platform android(and--serialwith an Apple platform) now fails as the flag mistake it is —INVALID_ARGSnaming the right flag — instead of reaching device resolution and answeringNo Apple device with UDID emulator-5580for an explicitly Android request.--udidaddresses Apple devices,--serialaddresses Android and HarmonyOS; matching pairs and requests that name no platform are unchanged. -
Breaking (
--session-lock strip): a device selector that names a different device than the bound session is no longer silently discarded.stripexists to drop redundant platform/scope selectors; when it also dropped--udid/--serial/--device, the command kept running against the bound device instead of the one the caller named — a wrong-device action that looks like a success. Such a request now fails withINVALID_ARGSunder bothrejectandstrip, and the error carries the two identities structurally (requestedDevice,boundDevice) plus a hint offering the two real recoveries: close the bound session if the requested device is intended, or remove the selector if the bound device is. The hint no longer suggests--session-lock stripfor an identity conflict, since following that advice is what produced the wrong-device run. Scope-only stripping (--platform,--target,--ios-simulator-device-set,--android-device-allowlist) is unchanged. -
iOS regular snapshots now apply one backend-neutral eligibility rule after every capture backend: a node survives when its accessibility type is interactive or it carries a non-empty label, identifier, or value. This removes the tree backend's extra "hittable non-Other" membership path and drops unlabeled decorative nodes consistently; labeled images, identifier-only nodes, and value-only nodes still survive. Raw snapshot membership is unchanged.
-
iOS regular snapshots now run one shared clip fold inside presentation for every capture backend (#1797). Backends serialize reported facts -- every traversed node, at raw traversal depth -- and presentation alone decides what the viewport and scroll clips hide, books the scroll hints, and collapses depth; no backend carries its own copy of that interpretation anymore (the copies are what produced the scroll-overflow leak class, #1784). Three intentional edge deltas ride along, all in the direction of one backend-neutral rule: sub-pixel content-free decorations are now dropped by every backend (previously private-AX only); labeled offscreen Application/Window carriers now survive on every backend (previously tree only), still never hittable; and a query-sweep recovery snapshot without
-ino longer lists offscreen elements. Nothing outside its clip, and nothing without geometry, is everhittablein a regular snapshot, whatever the backend reported. -
iOS
snapshot --rawis now the acquired accessibility tree on every backend that can serve it (#1797). A raw request that recovered onto the private-AX backend — the route an app whose XCTest tree capture fails takes — returned the regular projection's viewport-pruned nodes labeled raw: everything scrolled out of the viewport, and every sub-pixel decoration, was missing from the one view whose purpose is showing what the pruned view hid. Raw now keeps every node the backend serialized, at traversal depth, and--depthstill narrows it (for raw, presented depth is traversal depth). Two structural rules replace the hand-synchronized ones: the raw capture plan is derived from each backend's declared ability to serve raw, so the interactive query sweep — which has no hierarchy to return — cannot be planned for a raw request; and presentation refuses an acquisition captured for the other projection instead of relabeling it, dropping that tier with a structured failure. Breaking in the same direction:snapshot --raw -inow returns the acquired tree instead of an interactive-filtered one —-inarrows the regular projection, and the pair used to produce a third membership rule that differed per backend. Regular and-ioutput is unchanged. Backends now read one derived capture hint rather than the request itself, so what a capture is allowed to skip is stated once, next to the proof that skipping it keeps the projection complete. -
Android
snapshot --rawis now the acquired accessibility tree (#1832 C3): the regular-projection classifiers for nodes Android marks invisible and stale application windows no longer run at parse time, so--rawkeeps everything the helper serialized (normalization only). Covered same-window surfaces are publication annotations rather than membership pruning. Also: Android blocking-dialog recovery now reads the same daemon presentation an agent'ssnapshotsees instead of a hand-rolled subset, and acts on its occlusion result — a stale "App isn't responding" surface left under the foreground one no longer triggers recovery, and a covered "Close app" is never tapped ahead of the visible one; the Android freshness route signature no longer keys onrole, a field the Android backend never carries; and the Android helper's declared fidelity residues (nochecked/checkable/long-clickable, 5000-node cap before scoping, API-level cache-reset divergence) are recorded inCONTEXT.md. -
agent-device mcpnow carries its own usage guidance, so MCP-only clients (Codex CLI, Cursor, custom agents) no longer depend on a separately installed skill (#1833). The handshakeinstructions— returned by bothserver/discoverand, newly, the legacyinitialize— is a compact (< 2 KB, the Claude Code truncation limit) workflow card: start withopen {app, foreground: true}instead of probing, act withsettle: trueand continue from the diff, verify withwait/is/get/find, copy@refsbyte-for-byte, recover from sparse/AX-unavailable, follow error hints,close. A new MCP-onlyhelptool serves the full guides on demand: notopicreturns the CLI's decision card;topicreturnsagent-device help <topic|command>verbatim (workflow, gestures, scripting, tv, macos, web, remote, debugging, …, or any tool name for its complete flag reference), prefixed with the one-line CLI→tool-property mapping.helpis router-owned rather than a command descriptor, so it appears intools/listonly — not in the CLI, Node client, orbatch— and its description tells the model it is not a startup step. Legacyinitializegains the optionalinstructionsfield; no other legacy field changes. -
Android
snapshot --scope(and every selector command's--scope, e.g.press "Save" --scope Panel) now resolves scope exactly once, inside the Android projection, under the shared scope specification: the scope root is the first node in document order whose label, value, or identifier contains the scope text (case-insensitive) and whose subtree still has content in the projection you asked for, the result is that subtree re-rooted at depth 0, and no match returns an empty snapshot (#1832). That second clause is what makessnapshot -i --scope panelreturn the button inside a structural container-idrops, and stops a decorative heading that happens to match from emptying the snapshot. Before, Android ran two passes with contradictory rules — a breadth-first platform match that fell back to the full tree on a miss, then the daemon's document-order pass — so a shallower later container could win over an earlier match, and an interaction capture whose scope reached only the daemon layer was silently unscoped.--depthunder--scopecounts from the scope root, filtering the depths the response prints (a node shown at depth 0 is never hidden by--depth 0), and ancestor context above the scope root (a clickable row, a list) still shapes-imembership inside it. The rule is pinned bycontracts/fixtures/snapshot-scope-policy.json, the same golden table the iOS runner consumes (#1797). -
New
hover <x y|@ref|selector>command for--platform web(#1783). It moves the pointer over the target without pressing, so hover-gated UI — a message row's...toolbar, a menu that opens on pointer enter — becomes reachable through agent-device the way it already was through the underlyingagent-browserbackend (mouse move). It is a member of the targeted-touch family: same@ref/selector/coordinate targeting, occlusion and off-screen guards, and--settle(the settled diff carries the revealed controls with fresh refs, e.g.+ @e4 [button] "Delete"), but no--verify, since hover reveals rather than activates.hover @refpublishes as a portable selector line in recorded scripts, and the Node client exposesinteractions.hover. Hover is a pointer state that touch platforms do not have, socapabilitiesadvertises it on web only and iOS/Android/Linux reject it during admission withUNSUPPORTED_OPERATIONand a hint naming--platform web;longpressremains the mobile hold-gesture verb. -
Internal: session recording is now derived from the script-publication lifecycle instead of being stored beside it.
SessionState.recordSessionis removed;isRecordingPublicationanswers the question from the aggregate (ordinary authoring records only while ARMED, a repair transaction records for its whole lifetime). The stored flag was a second source of truth that handler surfaces set directly, which is how #1533's aborted-recording drift arose — no surface can now arm recording without moving the lifecycle that authorizes it, and the script writer's publication gate is answered entirely by the aggregate. Behavior-preserving: the derivation reproduces what the flag held at every transition. -
Fixed: a script recording aborted by a second
openis no longer published by a later bareclose(#1533).open <app> --save-scriptfollowed by a second successfulopenterminates the recording and warns "Script publication was aborted…", andclose --save-scriptcorrectly refuses it with "Retry with plain close; it will tear down the session without writing." But when that secondopenitself carried--save-script, the flag re-armed recording behind the terminal status, and a bareclosethen wrote the full session log to disk — publishing a recording the caller had been told was aborted, and breaking the promise the refusal makes. An aborted authoring lifecycle is now terminal by construction:--save-scriptarms nothing on any surface that handles it — the re-open builder, the close finalizer, and the recorded-action ingress — and the script writer refuses the lifecycle from every path that reaches it (bareclose, teardown, idle-reap, active publication). This also stops an aborted session from paying recording-time costs it can never publish: a re-opened aborted recording no longer keeps the direct iOS selector fast paths forclickandgetdisabled. Armed recordings, published recordings, and every repair transaction are unaffected. -
agent-device mcpnow serves the stateless MCP2026-07-28revision alongside the handshake-based revisions it already spoke, as the spec's "dual-era server". Modern clients probeserver/discover, which advertises the supported revisions, the tools capability, and server identity; their requests declare a protocol version in_meta, and their results carryresultType: "complete"plus_meta["io.modelcontextprotocol/serverInfo"].tools/listandserver/discovernow return thettlMs/cacheScopecache hints, so a client can cache the 55-tool, ~223KB tool list for an hour instead of re-fetching it on every start; the list was already emitted in a deterministic (sorted) order, which is the other half of what makes it cacheable. Each revision is answered on its own wire contract: a request declaring2025-11-25or2025-06-18through modern framing still gets the legacy result shape, andinitializenever agrees to2026-07-28, which has no handshake to establish. A declared revision this server does not implement is rejected withUnsupportedProtocolVersionError(-32022) naming the ones it does, rather than being served under a version the client did not ask for, and modern framing that omits its requiredprotocolVersion/clientCapabilitiesmetadata — or supplies aclientInfothat is not a validImplementation— is rejected as invalid params.initializeandpingwere removed in2026-07-28, so a modern-framed call to either is answered-32601rather than served inside aresultType: "complete"envelope. Responses to legacy clients are unchanged byte-for-byte —initializeandpingare still served, and no cache,resultType, or_metafield is added to their results. Nothing here affects the CLI, Node, or daemon surfaces: the stdio transport, the tool set, and every tool's input/output schema are untouched. -
Fixed: the MCP
initializehandshake now answers with the protocol revision the client requested when it is one this server implements, instead of always answering2025-11-25. A client pinned to2025-06-18was told to speak a revision it had not asked for, which the lifecycle contract answers by disconnecting. -
agent-device help workflowis now a compact ~8KB card instead of a ~41KB dump; the same depth still exists, split intohelp scripting(save-script, secret-safe fills, batch JSON, replay divergence/repair, recording) andhelp gestures(multi-touch shapes and platform quirks), plus a few paragraphs folded into the topics that already owned the subject (help debugging,help physical-device,help validate). Everyhelp <topic>first line is nowagent-device <version> — <topic>so an agent can read the installed version from its mandatory first help read instead of a separateagent-device --versioncall. -
Cloud iOS (BrowserStack, AWS Device Farm):
snapshotanddiffno longer fail withSESSION_NOT_FOUNDon a live provider session (#1658). The app-session guard they ran belongs to the local XCUITest runner, which must attach to a target app; a cloud capture reads the provider's own driver session and needs no app identity, so the guard now applies to local Apple targets only. Relatedly, a cloud iOSopen com.example.appnow records that bundle id on the session — the provider path skips local app resolution (no simctl/devicectl reaches a hosted device), and used to drop an explicitly spelled bundle id along with it, leaving the session with no app identity at all. Opening a second bundle id replaces the first, matching the local path, where an explicitly spelled target always wins over the session's current app; deep links, display names, and bareopenstill keep the app already tracked. -
Cloud
fill(BrowserStack, AWS Device Farm) now witnesses that the field it tapped actually holds text-entry focus before sending its keys, instead of dispatching tap and keys in back-to-back requests (#1658). A WebView input — an OAuth/SSO page in a Safari view controller, for example — takes first responder asynchronously, so the keys used to land with nothing focused whilefillstill answered "Filled N chars"; tapping and filling as two separate commands worked only because the round trip between them gave the field time to focus. The witness is the focused element's own geometry:fillpolls the active element and proceeds only once it contains the point it tapped, which is the one signal that identifies which field took focus. Keyboard visibility cannot — it reads the same before and after a second fill into an already-open form, so it could not tell a focused password field from the email field the previous fill left focused. The response disclosestextEntryReadiness:focused-element, orkeyboard-shownwhen the driver has no active-element route but the keyboard rose from hidden after the tap. Both describe a fill that witnessed focus before typing; there is deliberately no value for typing without evidence, because nothing renders this field and such a value would reach a caller as an ordinary success. Breaking: when focus cannot be witnessed, cloudfillnow FAILS withCOMMAND_FAILED/text_entry_focus_not_observedand sends no keys, instead of typing into whatever holds first responder and answering "Filled N chars" — a fill with no witness must not read as a filled field. That covers a tap that focused nothing, a keyboard already up on a driver that cannot name the focused field, and a driver that reports neither (text_entry_focus_unobservable, which points atpress+typeas the deliberate way to enter text unwitnessed). Only a positively classified unimplemented route counts as unsupported, so a dead session, an auth rejection, or a grid outage surfaces instead of degrading into a blind text entry. -
Changed mutating selector ambiguity semantics (press/click/fill/longpress): duplicate accessibility wrappers collapse only when every match forms one ancestor-descendant chain resolving to the same actionable node. Matches in distinct subtrees now fail fast with
AMBIGUOUS_MATCHand a bounded, immediately reusable candidate-ref frame; visible/depth/area geometry no longer silently picks a mutation target. The direct iOS XCTest path now counts raw exact matches before hittability and delegates ambiguity to the same runtime rule. AppControlBench provenance: element-14 ran on 0.20.5; this change is intended for 0.20.7+, and comparative benchmark reports should note that it can replace a wrong-success recovery loop with one candidate-pick turn while occasionally adding that turn for genuinely distinct duplicates. -
scrollandbacknow accept--settle(with--settle-quietand--timeout), collapsing scroll-then-observe and back-then-observe into one call (#1638). The response carries the same settled payload the touch commands return — verdict, changed-lines diff with fresh refs on added lines, the unchanged-interactive tail, andrefsGenerationwhen the settled tree was stored — and is best-effort: it never fails the action. One difference is deliberate:scroll/backresolve no element, so the diff baseline is the session's stored pre-action tree ("the last tree you observed") rather than a freshly resolved pre-action capture. Both commands now also preserve the daemon on timeout, like the other settle-capable commands. -
Security: repository
./agent-device.jsonnow accepts only project-safe automation defaults. It rejects daemon endpoint/auth/transport/server settings, tenant/run/lease selectors, provider/cloud and Metro connection fields, headers, executable reporter modules, local write destinations, and other operator-controlled values before local module loading or any daemon health/RPC request. Put remote endpoint and token together in protected CI environment variables, user config, an explicit--configfile, or the existingconnect/--remote-configworkflow. Daemon auth tokens no longer travel in serialized command flags. -
viewportis now rejected during capability admission on Apple targets instead of reaching the device and failing inside dispatch. No Apple backend can resize a screen — simulator and device geometry is fixed by the selected device type — soviewporton iOS/iPadOS/tvOS/macOS now fails withUNSUPPORTED_OPERATION,viewport is not supported on this device, and a hint pointing at--platform weband at picking a different simulator.capabilitiesno longer advertisesviewporton Apple targets. Web viewport resizing (agent-device viewport 1280 900 --platform web) is unchanged, and Android was already denied. -
--save-scriptis now accepted only by the commands that declare it —open,close, andreplay. A hand-built daemon request (or abatchstep) that setsaveScripton any other command, such asrecordortrace, used to arm script publication and could write a.adartifact; it is now rejected withINVALID_ARGSbefore the request reaches admission, the device, or any handler. CLI, Node, and MCP usage of--save-scripton its documented commands is unchanged. -
diff screenshotno longer runs the retired best-effort OCR and non-text analyzers. Their optionalocrandnonTextDeltasfields remain in the result type for source compatibility but are no longer emitted; use the baseline/current images and diff artifact with vision for qualitative interpretation. -
Breaking: removed the deprecated
--session-lockedand--session-lock-conflictsflags. Use--session-lock reject|stripinstead; passing either old flag now fails withUnknown flag: ... Use --session-lock reject|strip instead. -
Breaking: removed the
replay export --formatflag.replay exportalways writes Maestro YAML. -
Breaking: removed the unused
LeaseAllocatePayload,LeaseHeartbeatPayload, andLeaseReleasePayloadtype exports fromagent-device/contracts. Lease request metadata is fully described byDaemonRequestMeta. -
Maestro compat:
assertVisibleandassertNotVisiblenow acceptchildOffor ancestor scoping, matchingtapOn(#1294). -
Breaking: removed deprecated gesture duration and rotate velocity inputs (#1218).
swipe x1 y1 x2 y2no longer accepts a trailingdurationMspositional; usegesture pan x1 y1 (x2-x1) (y2-y1) durationMsfor deliberate timed drags.- Maestro
swipeoperations with a duration continue to normalize togesture panwith theendpoint-holdexecution profile, preserving the Maestro-compatible fast-swipe-then-hold behavior on iOS. gesture fling direction x yno longer accepts a trailingdurationMspositional; usegesture panfor timed movement.gesture swipe presetno longer accepts a trailingdurationMspositional; usegesture panfor timed movement.gesture rotate degrees [x] [y]no longer accepts a trailingvelocitypositional; rotation pacing is derived fromdegrees.- MCP/Node schemas no longer advertise
velocityordurationMsonswipe/fling/gesture swipe;durationMsremains ongesture panandgesture transform. - A
.adscript that still carries a removed positional now fails when the script is parsed, before the replay executes any device action, naming the line and its rewrite (for exampleswipe accepts 4 arguments: x1 y1 x2 y2 (line 6). The trailing durationMs positional was removed: use "gesture pan 197 650 0 -350 300" ...). Previously the script ran up to that step and then failed as a replay divergence. - Published the gesture migration guide covering CLI, Node.js, MCP, and saved
.adrecordings, plus the deprecation policy the next such removal follows (#1216). replay exportnow writes an explicitduration: 100forswipe— the canonical fling duration — instead of omitting it and letting Maestro apply its own 400ms default. Maestro flows replayed byagent-deviceare unaffected; a timed Maestroswipestill normalizes togesture panwith theendpoint-holdprofile.
-
Breaking: the deprecated
rotateCLI command alias has been removed. Useorientationinstead; invokingrotatenow fails withrotate was renamed to orientation; for the two-finger gesture use: gesture rotate. -
Breaking (ADR 0014, session ref-frame lifetime): a mutation through an
@refnow expires the session's ref frame, so a later ref mutation without a fresh observation fails closed with a typeddetails.reason(ref_frame_expired,ref_generation_mismatch,plain_ref_requires_complete_frame, orref_not_issued) instead of acting on a possibly-navigated screen. A ref-oriented sequence that performs several mutations must re-snapshotbetween them, consume an honestly issued--settleref in pinned@eN~s<gen>form, or use selectors. Enforcement applies on every platform, not just iOS. Legacy hand-written.adscripts that reuse several bare refs from one snapshot must capture between mutations or use selectors. -
Ref reads resolve against the authorized ref frame's source tree, so an internal read-only capture (including Android freshness) can no longer retarget an admitted
@refby positional coincidence. Read-only ref consumers keep the structured staleness warning while the frame retains the ref's evidence.
- Breaking:
appsdiscovery and public app-list helpers now default to user-installed apps. Use--allorfilter: 'all'to include system/OEM apps. - Breaking: removed the
agent-device/android-appspublic subpath. Use the Android app helpers fromagent-device/android-adb. - Breaking: removed the
agent-device/daemonpublic subpath. Useagent-device/contractsfor daemon request/response types. - Breaking: removed public local ADB bypass/selection helpers such as
spawnAndroidAdbBySerialandresolveAndroidAdbProvider; usecreateLocalAndroidAdbProvider(device)or pass providers directly to the helpers fromagent-device/android-adb. - Added Android ADB provider helpers for exec, stream, clipboard, keyboard, app lifecycle, logcat, and port reverse workflows.