# Changelog

## Unreleased

- 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: true` in 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 `--scope` as 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 `selected` state an app sets on a control, so
  `is selected`, a `selected=true` selector, and a Maestro `selected:` 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 attrs` had no `selected` field, 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 — while `selected: false`
  matched every Android node. The helper now emits both answers, like `enabled` and `password`, so
  an unselected control answers `false` and a helper older than the attribute answers nothing; the
  host parser, the Android hierarchy node, and the published snapshot node carry it through to
  `get attrs` and the `[selected]` marker in snapshot text. Snapshot lines now render that marker
  whenever selection is rendered, not only when text surfaces are summarized: `--settle` and `diff`
  already 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 `256` that
  could wrap to success and hide a failing suite. `getExitCode` accepts integers from `0` to `255`
  or `undefined`; JSON output reports an invalid code as one `INVALID_ARGS` error.
- Fixed: Android `record start` no 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 start` then failed every later
  attempt with `Android screenrecord completed evidence cannot be safely retired`, and `record stop`
  could 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 replacement `screenrecord` on 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: a polling `wait` no longer surrenders its whole budget the first time the iOS runner
  answers `RUNNER_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 a
  `wait text ... 20000` could 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 as
  `retriable` in 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 own `captures`, `readableCaptures`, `waitedMs` and `polls`, 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_BUSY` reached
  callers as a bare `RUNNER_BUSY` wire code without the `retriable` flag on that path, while the
  live path published it as `COMMAND_FAILED` with `details.runnerErrorCode` and `retriable: true`;
  both paths now read the runner's code through one classifier.
- Fixed: iOS Simulator snapshots of Safari and of apps with a `WKWebView` stopped 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
  an `AXRemoteElement` leaf 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: `test` expands 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 export` preserves deep links without `//`, including `tel:` and `mailto:`, as
  Maestro `openLink` commands in both standalone and app-plus-link `open` actions.
- Changed: a command whose synopsis is generated names each option with the label its declaration
  carries, so `snapshot` now shows `--depth, -d <depth>` and `--scope, -s <scope>` where it used to
  show the short aliases, and `--record` is documented under `Command flags:` instead of inside the
  `snapshot` and `is` synopsis lines. `snapshot`, `proxy`, `daemon`, `device`, `doctor`, `prepare`
  and `tv-remote` no longer restate their option list in a hand-written usage string, so adding an
  option to those commands updates `--help` on its own (#2444).
- Fixed: iOS `--depth` on `snapshot`, `is`, `wait`, `get`, and `find` no longer fails with
  `regular iOS snapshot presentation requires a valid viewport` when 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 now
  `regular-depth=presentation-cut` and an acquisition that stopped short of the cut keeps
  disclosing that through `truncated`/`effectiveDepth` as 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 dump` no 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 no `url:` 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, with `pathUnavailable` set, 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's `unnamedRequests`, 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's `url` compares 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 export` supports flows that switch apps and return, preserving each
  `open <appId>` target as an explicit Maestro `launchApp.appId`.
- Added: `replay export` converts recorded `home` actions to Maestro `pressKey: Home`, allowing
  app-to-home-to-app journeys to be exported.
- Added: polling `wait` timeouts (`wait <selector>`, `wait text`, `wait @ref`, and `wait absent`
  after a readable capture) carry a per-poll timeline in `error.details` (`captures`, `polls[]`
  with `startedMs`, `durationMs`, and a typed `outcome`: readable, unreadable, deadline,
  runner-restart) next to the unchanged `reason`, 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
  --stable` timeouts and a never-readable strict absence keep their existing diagnostics.
- Fixed: Android `orientation` now returns once the display reports the requested rotation
  (polling `dumpsys 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; a `wait` issued right after `orientation` could 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 list` through 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 a `wait` issued right after `open` could spend its budget on
  probe timeouts and report `wait_capture_stalled` with the app already on screen.
- Fixed: iOS snapshots no longer report `truncated: true` merely 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 strict `is absent` / `wait absent`
  refused it with "capture was truncated" on loaded CI hosts. `truncated` now tracks completeness
  only: payload truncation, a depth-limited capture, or a sparse terminal payload.
- Fixed: Android `alert accept` / `alert dismiss` return 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 with
  `alert <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 status` lists it in the normal
  view (never as stale), `device release --stale` refuses it with `allocator-held-owner`, the
  daemon-startup sweep and session close leave it alone, and a command that binds the device
  ordinarily is refused `DEVICE_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, and
  `devices` reports no `claimedBy` for such a device until the managed-inventory filter lands.
- Added the `harmonyos-instance` lease 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|off` now takes an Android device offline. It is applied through
  the connectivity service (`cmd connectivity airplane-mode`), which drives the radios, instead of
  writing `airplane_mode_on` and broadcasting `ACTION_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 the
   `airplaneMode` the connectivity service holds after the change, and an Android build that does not
   expose that command is refused with `UNSUPPORTED_OPERATION` before anything is written.
- Fixed: the MCP registry entry (`server.json`) now declares the fixed `mcp` subcommand via
  `packageArguments`, so a registry-format launcher — the MCP Registry or the website's
  `/.well-known/mcp.json` discovery manifest — starts the stdio MCP server. Previously it ran
  `agent-device` with 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 `truncated` field is optional when Appium cannot report
  hierarchy completeness; regular snapshots fail closed without valid viewport evidence, while
  `snapshot --raw` remains available for diagnostics (#2195).
- Security (daemon, remote/proxy HTTP only): when `AGENT_DEVICE_HTTP_AUTH_HOOK` is configured and a
  request's hook result does not attest a `tenantId`, the request is now refused (401) outright — the
  daemon no longer runs it as whichever tenant the client declared (RPC body `meta.tenantId` or
  `flags.tenant`, or the `x-agent-device-tenant` header 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 attest `tenantId` on every request it wants the daemon to admit.
- Breaking (0.21): removed aggregate performance compatibility (`perf`, `perf sample`, `perf metrics`, the `metrics` alias, optionless `client.observability.perf()`, and SDK `area: 'metrics'`). Use `perf frames`, `perf memory sample`, `perf cpu profile start|stop|report`, or `perf 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.rotate` wrapper and its `RotateCommandOptions` / `RotateCommandResult` exports. Use `command.orientation`; the already-removed CLI `rotate` form keeps its targeted migration error.
- Security (MCP/AI-SDK tool surface): the operator-owned endpoint and path inputs — `daemonBaseUrl`,
  the Metro `proxyBaseUrl`, `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-writable `daemonBaseUrl`/`proxyBaseUrl` would redirect the
  env-resolved token to an arbitrary server). Dropping these plus the credential fields shrinks
  `tools/list` by 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 `test` runner), 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/call` argument must appear in the tool's
  advertised (`additionalProperties: false`) schema, or it is refused before config/env resolution.
  Hiding a key from `tools/list` alone was insufficient: the router forwards raw arguments verbatim
  and the MCP config resolver read `config`/`remoteConfig` as CLI flags, so a model-supplied config
  file could load `daemonBaseUrl`/`daemonAuthToken` and 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): `daemonAuthToken` and the Metro `bearerToken` are no longer
  advertised as tool input properties, and an explicit value is refused with guidance instead of
  being forwarded. Credentials are operator-owned: set `AGENT_DEVICE_DAEMON_AUTH_TOKEN` (or
  `daemonAuthToken` in `~/.agent-device/config.json`) and `AGENT_DEVICE_METRO_BEARER_TOKEN` on 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-dev` moves `main` to the next patch with a
  `-dev` prerelease marker so the version on `main` never 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:prepare` refuses to publish while the `-dev` marker is in place.
- Windows `--platform web` works again. `agent-device web setup` no longer fails with
  `npm not found in PATH`, and every web command — including `web doctor` — no longer fails with
  `spawn EINVAL`. The managed `agent-browser` backend is now launched as `node <js-entry>` on every
  platform instead of through its `node_modules/.bin` console shim, which is a `.cmd` file on
  Windows that `child_process.spawn` refuses without a shell (CVE-2024-27980 hardening);
  `shell: true` would only trade that for argument-quoting hazards and a `DEP0190` warning on every
  command. Setup spawns `npm` from PATH unchanged on macOS and Linux, and runs npm's own
  `npm-cli.js` under the current Node only on Windows, where a bare `npm` is not spawnable. A
  managed install now counts as present only when the backend package itself is, and
  `web setup --json` / `web doctor --json` gain `entryScript` and `packageDir`; the published
  `binaryPath` is unchanged and still names npm's console shim, now informational rather than the
  spawned command (#2022).
- Parameterized `fill --record-as` protection 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 or
  `target-v1` identity evidence. An echoing `wait` landmark no longer qualifies as an ADR 0016
  destination guard, so `session save-script` refuses 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-only `drawing-order` stays private rather than entering
  the snapshot contract, sparse floating overlays remain usable, and API 23 fails conservative with
  the existing `androidSnapshot.occlusionScanUnavailable` disclosure (#1832).
- iOS regular `snapshot --depth` now 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 `--depth`
  remains 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
  `rect` field: 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:android` when 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 with `AMBIGUOUS_MATCH` and 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. `devices` and other genuinely multi-device commands never enter singular resolution and are unaffected. The error carries the bounded candidate list in the declared `devices` details domain, so CLI and MCP print it, with a hint naming the right selector for the platform (`--serial` for Android/HarmonyOS, `--udid` for Apple, or `--device "<name>"`).
- `--udid` with `--platform android` (and `--serial` with an Apple platform) now fails as the flag mistake it is — `INVALID_ARGS` naming the right flag — instead of reaching device resolution and answering `No Apple device with UDID emulator-5580` for an explicitly Android request. `--udid` addresses Apple devices, `--serial` addresses 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. `strip` exists 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 with `INVALID_ARGS` under both `reject` and `strip`, 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 strip` for 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 `-i` no longer lists offscreen elements. Nothing outside its clip, and nothing without geometry, is ever `hittable` in a regular snapshot, whatever the backend reported.
- iOS `snapshot --raw` is 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 `--depth` still 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 -i` now returns the acquired tree instead of an interactive-filtered one — `-i` narrows the regular projection, and the pair used to produce a third membership rule that differed per backend. Regular and `-i` output 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 --raw` is 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 `--raw` keeps 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's `snapshot` sees 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 on `role`, a field the Android backend never carries; and the Android helper's declared fidelity residues (no `checked`/`checkable`/`long-clickable`, 5000-node cap before scoping, API-level cache-reset divergence) are recorded in `CONTEXT.md`.
- `agent-device mcp` now carries its own usage guidance, so MCP-only clients (Codex CLI, Cursor, custom agents) no longer depend on a separately installed skill (#1833). The handshake `instructions` — returned by both `server/discover` and, newly, the legacy `initialize` — is a compact (< 2 KB, the Claude Code truncation limit) workflow card: start with `open {app, foreground: true}` instead of probing, act with `settle: true` and continue from the diff, verify with `wait`/`is`/`get`/`find`, copy `@refs` byte-for-byte, recover from sparse/AX-unavailable, follow error hints, `close`. A new MCP-only `help` tool serves the full guides on demand: no `topic` returns the CLI's decision card; `topic` returns `agent-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. `help` is router-owned rather than a command descriptor, so it appears in `tools/list` only — not in the CLI, Node client, or `batch` — and its description tells the model it is not a startup step. Legacy `initialize` gains the optional `instructions` field; 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 makes `snapshot -i --scope panel` return the button inside a structural container `-i` drops, 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. `--depth` under `--scope` counts 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 `-i` membership inside it. The rule is pinned by `contracts/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 underlying `agent-browser` backend (`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 @ref` publishes as a portable selector line in recorded scripts, and the Node client exposes `interactions.hover`. Hover is a pointer state that touch platforms do not have, so `capabilities` advertises it on web only and iOS/Android/Linux reject it during admission with `UNSUPPORTED_OPERATION` and a hint naming `--platform web`; `longpress` remains the mobile hold-gesture verb.
- Internal: session recording is now derived from the script-publication lifecycle instead of being stored beside it. `SessionState.recordSession` is removed; `isRecordingPublication` answers 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 `open` is no longer published by a later bare `close` (#1533). `open <app> --save-script` followed by a second successful `open` terminates the recording and warns "Script publication was aborted…", and `close --save-script` correctly refuses it with "Retry with plain close; it will tear down the session without writing." But when that second `open` itself carried `--save-script`, the flag re-armed recording behind the terminal status, and a bare `close` then 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-script` arms 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 (bare `close`, 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 for `click` and `get` disabled. Armed recordings, published recordings, and every repair transaction are unaffected.
- `agent-device mcp` now serves the stateless MCP `2026-07-28` revision alongside the handshake-based revisions it already spoke, as the spec's "dual-era server". Modern clients probe `server/discover`, which advertises the supported revisions, the tools capability, and server identity; their requests declare a protocol version in `_meta`, and their results carry `resultType: "complete"` plus `_meta["io.modelcontextprotocol/serverInfo"]`. `tools/list` and `server/discover` now return the `ttlMs`/`cacheScope` cache 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 declaring `2025-11-25` or `2025-06-18` through modern framing still gets the legacy result shape, and `initialize` never agrees to `2026-07-28`, which has no handshake to establish. A declared revision this server does not implement is rejected with `UnsupportedProtocolVersionError` (`-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 required `protocolVersion`/`clientCapabilities` metadata — or supplies a `clientInfo` that is not a valid `Implementation` — is rejected as invalid params. `initialize` and `ping` were removed in `2026-07-28`, so a modern-framed call to either is answered `-32601` rather than served inside a `resultType: "complete"` envelope. Responses to legacy clients are unchanged byte-for-byte — `initialize` and `ping` are still served, and no cache, `resultType`, or `_meta` field 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 `initialize` handshake now answers with the protocol revision the client requested when it is one this server implements, instead of always answering `2025-11-25`. A client pinned to `2025-06-18` was told to speak a revision it had not asked for, which the lifecycle contract answers by disconnecting.
- `agent-device help workflow` is now a compact ~8KB card instead of a ~41KB dump; the same depth still exists, split into `help scripting` (save-script, secret-safe fills, batch JSON, replay divergence/repair, recording) and `help 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`). Every `help <topic>` first line is now `agent-device <version> — <topic>` so an agent can read the installed version from its mandatory first help read instead of a separate `agent-device --version` call.
- Cloud iOS (BrowserStack, AWS Device Farm): `snapshot` and `diff` no longer fail with `SESSION_NOT_FOUND` on 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 iOS `open com.example.app` now 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 bare `open` still 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 while `fill` still 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: `fill` polls 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 discloses `textEntryReadiness`: `focused-element`, or `keyboard-shown` when 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, cloud `fill` now FAILS with `COMMAND_FAILED` / `text_entry_focus_not_observed` and 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 at `press` + `type` as 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_MATCH` and 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.
- `scroll` and `back` now accept `--settle` (with `--settle-quiet` and `--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, and `refsGeneration` when the settled tree was stored — and is best-effort: it never fails the action. One difference is deliberate: `scroll`/`back` resolve 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.json` now 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 `--config` file, or the existing `connect`/`--remote-config` workflow. Daemon auth tokens no longer travel in serialized command flags.
- `viewport` is 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 — so `viewport` on iOS/iPadOS/tvOS/macOS now fails with `UNSUPPORTED_OPERATION`, `viewport is not supported on this device`, and a hint pointing at `--platform web` and at picking a different simulator. `capabilities` no longer advertises `viewport` on Apple targets. Web viewport resizing (`agent-device viewport 1280 900 --platform web`) is unchanged, and Android was already denied.
- `--save-script` is now accepted only by the commands that declare it — `open`, `close`, and `replay`. A hand-built daemon request (or a `batch` step) that set `saveScript` on any other command, such as `record` or `trace`, used to arm script publication and could write a `.ad` artifact; it is now rejected with `INVALID_ARGS` before the request reaches admission, the device, or any handler. CLI, Node, and MCP usage of `--save-script` on its documented commands is unchanged.
- `diff screenshot` no longer runs the retired best-effort OCR and non-text analyzers. Their optional `ocr` and `nonTextDeltas` fields 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-locked` and `--session-lock-conflicts` flags. Use `--session-lock reject|strip` instead; passing either old flag now fails with `Unknown flag: ... Use --session-lock reject|strip instead.`
- Breaking: removed the `replay export --format` flag. `replay export` always writes Maestro YAML.
- Breaking: removed the unused `LeaseAllocatePayload`, `LeaseHeartbeatPayload`, and `LeaseReleasePayload` type exports from `agent-device/contracts`. Lease request metadata is fully described by `DaemonRequestMeta`.
- Maestro compat: `assertVisible` and `assertNotVisible` now accept `childOf` for ancestor scoping, matching `tapOn` (#1294).
- Breaking: removed deprecated gesture duration and rotate velocity inputs (#1218).
  - `swipe x1 y1 x2 y2` no longer accepts a trailing `durationMs` positional; use `gesture pan x1 y1 (x2-x1) (y2-y1) durationMs` for deliberate timed drags.
  - Maestro `swipe` operations with a duration continue to normalize to `gesture pan` with the `endpoint-hold` execution profile, preserving the Maestro-compatible fast-swipe-then-hold behavior on iOS.
  - `gesture fling direction x y` no longer accepts a trailing `durationMs` positional; use `gesture pan` for timed movement.
  - `gesture swipe preset` no longer accepts a trailing `durationMs` positional; use `gesture pan` for timed movement.
  - `gesture rotate degrees [x] [y]` no longer accepts a trailing `velocity` positional; rotation pacing is derived from `degrees`.
  - MCP/Node schemas no longer advertise `velocity` or `durationMs` on `swipe`/`fling`/`gesture swipe`; `durationMs` remains on `gesture pan` and `gesture transform`.
  - A `.ad` script 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 example `swipe 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](https://agent-device.dev/docs/migrating-gestures) covering CLI, Node.js, MCP, and saved `.ad` recordings, plus the deprecation policy the next such removal follows (#1216).
  - `replay export` now writes an explicit `duration: 100` for `swipe` — the canonical fling duration — instead of omitting it and letting Maestro apply its own 400ms default. Maestro flows replayed by `agent-device` are unaffected; a timed Maestro `swipe` still normalizes to `gesture pan` with the `endpoint-hold` profile.
- Breaking: the deprecated `rotate` CLI command alias has been removed. Use `orientation` instead; invoking `rotate` now fails with `rotate was renamed to orientation; for the two-finger gesture use: gesture rotate`.
- Breaking (ADR 0014, session ref-frame lifetime): a mutation through an `@ref` now expires the session's ref frame, so a later ref mutation without a fresh observation fails closed with a typed `details.reason` (`ref_frame_expired`, `ref_generation_mismatch`, `plain_ref_requires_complete_frame`, or `ref_not_issued`) instead of acting on a possibly-navigated screen. A ref-oriented sequence that performs several mutations must re-`snapshot` between them, consume an honestly issued `--settle` ref in pinned `@eN~s<gen>` form, or use selectors. Enforcement applies on every platform, not just iOS. Legacy hand-written `.ad` scripts 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 `@ref` by positional coincidence. Read-only ref consumers keep the structured staleness warning while the frame retains the ref's evidence.

## 0.15.0

- Breaking: `apps` discovery and public app-list helpers now default to user-installed apps. Use `--all` or `filter: 'all'` to include system/OEM apps.
- Breaking: removed the `agent-device/android-apps` public subpath. Use the Android app helpers from `agent-device/android-adb`.
- Breaking: removed the `agent-device/daemon` public subpath. Use `agent-device/contracts` for daemon request/response types.
- Breaking: removed public local ADB bypass/selection helpers such as `spawnAndroidAdbBySerial` and `resolveAndroidAdbProvider`; use `createLocalAndroidAdbProvider(device)` or pass providers directly to the helpers from `agent-device/android-adb`.
- Added Android ADB provider helpers for exec, stream, clipboard, keyboard, app lifecycle, logcat, and port reverse workflows.