agent-device 0.10.0 → 0.10.2

package/skills/agent-device/references/verification.md

@@ -0,0 +1,103 @@
+# Verification
+
+## When to open this file
+
+Open this file when the task needs evidence, regression checks, replay maintenance, or startup performance measurements after the main interaction flow is already working.
+
+## Main commands to reach for first
+
+- `screenshot`
+- `diff snapshot`
+- `record`
+- `replay -u`
+- `perf`
+
+## Most common mistake to avoid
+
+Do not use verification tools as the first exploration step. First get the app into the correct state with the normal interaction flow, then capture proof or maintain replay assets.
+
+## Canonical loop
+
+```bash
+agent-device open Settings --platform ios
+agent-device snapshot -i
+agent-device press @e5
+agent-device diff snapshot -i
+agent-device screenshot /tmp/settings-proof.png
+agent-device close
+```
+
+## Structural verification with diff snapshot
+
+Use `diff snapshot` when you need a compact view of how the UI changed between nearby states.
+
+```bash
+agent-device snapshot -i
+agent-device press @e5
+agent-device diff snapshot -i
+```
+
+- Initialize the baseline at a stable point.
+- Perform the mutation.
+- Run `diff snapshot` to confirm the expected structural change.
+- Re-run full `snapshot` only when you need fresh refs.
+
+## Visual artifacts
+
+Use `screenshot` when the proof needs a rendered image instead of a structural tree.
+
+## Session recording
+
+Use `record` for debugging, documentation, or shareable verification artifacts.
+
+```bash
+agent-device record start ./recordings/ios.mov
+agent-device open App
+agent-device snapshot -i
+agent-device press @e3
+agent-device close
+agent-device record stop
+```
+
+- `record` supports iOS simulators, iOS devices, and Android.
+- On iOS, recording is a wrapper around `simctl` for simulators and the corresponding device capture path for physical devices.
+- On Android, recording is a wrapper around `adb`.
+- Recording writes a video artifact and a gesture-telemetry sidecar JSON.
+- On macOS hosts, touch overlay burn-in is available for supported recordings.
+- On non-macOS hosts, recording still succeeds but the video stays raw and `record stop` can return an `overlayWarning`.
+- If the agent already knows the interaction sequence and wants a more lifelike, uninterrupted recording, drive the flow with `batch` while recording instead of replanning between each step.
+
+Example:
+
+```bash
+agent-device record start ./recordings/smoke.mov
+agent-device batch --session sim --platform ios --steps-file /tmp/smoke-steps.json --json
+agent-device record stop
+```
+
+- Use this only after exploration has stabilized the flow.
+- Keep the batch short and add `wait` or `is exists` guards after mutating steps so the recorded flow still tracks realistic UI timing.
+
+## Replay maintenance
+
+Use replay updates when selectors drift but the recorded scenario is still correct.
+
+```bash
+agent-device replay -u ./session.ad
+```
+
+- Prefer selector-based actions in recorded `.ad` replays.
+- Use update mode for maintenance, not as a substitute for fixing a broken interaction strategy.
+
+## Performance checks
+
+Use `perf --json` or `metrics --json` when you need startup timing for the active session.
+
+```bash
+agent-device open Settings --platform ios
+agent-device perf --json
+```
+
+- Current startup data is command round-trip timing around `open`.
+- It is not true first-frame or first-interactive telemetry.
+- `fps`, `memory`, and `cpu` are currently placeholders.

package/dist/src/274.js

@@ -1 +0,0 @@
-import{AppError as e}from"./331.js";let t="<wifi|airplane|location> <on|off>",r="appearance <light|dark|toggle>",a="faceid <match|nonmatch|enroll|unenroll>",i="touchid <match|nonmatch|enroll|unenroll>",n="fingerprint <match|nonmatch>",s="permission <grant|deny|reset> <camera|microphone|photos|contacts|contacts-limited|notifications|calendar|location|location-always|media-library|motion|reminders|siri> [full|limited]",o=`settings ${t} | settings ${r} | settings ${a} | settings ${i} | settings ${n} | settings ${s}`,l=`settings requires ${t}, ${r}, ${a}, ${i}, ${n}, or ${s}`;function c(e){let t=[],r=[];for(let a of e){let e=a.depth??0;for(;t.length>0&&e<=t[t.length-1];)t.pop();let i=a.label?.trim()||a.value?.trim()||a.identifier?.trim()||"",n=d(a.type??"Element"),s="group"===n&&!i;s&&t.push(e);let o=s?e:Math.max(0,e-t.length);r.push({node:a,depth:o,type:n,text:u(a,o,s,n)})}return r}function u(e,t,r,a){let i=a??d(e.type??"Element"),n=m(e,i),s="  ".repeat(t),o=e.ref?`@${e.ref}`:"",l=[!1===e.enabled?"disabled":null].filter(Boolean).join(", "),c=l?` [${l}]`:"",u=n?` "${n}"`:"";return r?`${s}${o} [${i}]${c}`.trimEnd():`${s}${o} [${i}]${u}${c}`.trimEnd()}function m(e,t){var r,a;let i=e.label?.trim(),n=e.value?.trim();if("text-field"===(r=t)||"text-view"===r||"search"===r){if(n)return n;if(i)return i}else if(i)return i;if(n)return n;let s=e.identifier?.trim();return!s||(a=s,/^[\w.]+:id\/[\w.-]+$/i.test(a)&&("group"===t||"image"===t||"list"===t||"collection"===t))?"":s}function d(e){let t=e.replace(/XCUIElementType/gi,"").toLowerCase(),r=e.includes(".")&&(e.startsWith("android.")||e.startsWith("androidx.")||e.startsWith("com."));switch(t.includes(".")&&(t=t.replace(/^android\.widget\./,"").replace(/^android\.view\./,"").replace(/^android\.webkit\./,"").replace(/^androidx\./,"").replace(/^com\.google\.android\./,"").replace(/^com\.android\./,"")),t){case"application":return"application";case"navigationbar":return"navigation-bar";case"tabbar":return"tab-bar";case"button":case"imagebutton":return"button";case"link":return"link";case"cell":return"cell";case"statictext":case"checkedtextview":return"text";case"textfield":case"edittext":return"text-field";case"textview":return r?"text":"text-view";case"textarea":return"text-view";case"switch":return"switch";case"slider":return"slider";case"image":case"imageview":return"image";case"webview":return"webview";case"framelayout":case"linearlayout":case"relativelayout":case"constraintlayout":case"viewgroup":case"view":case"group":return"group";case"listview":case"recyclerview":return"list";case"collectionview":return"collection";case"searchfield":return"search";case"segmentedcontrol":return"segmented-control";case"window":return"window";case"checkbox":return"checkbox";case"radio":return"radio";case"menuitem":return"menu-item";case"toolbar":return"toolbar";case"scrollarea":case"scrollview":case"nestedscrollview":return"scroll-area";case"table":return"table";default:return t||"element"}}let p=100,h=new Set(["batch","replay"]);function f(t){let r;try{r=JSON.parse(t)}catch{throw new e("INVALID_ARGS","Batch steps must be valid JSON.")}if(!Array.isArray(r)||0===r.length)throw new e("INVALID_ARGS","Batch steps must be a non-empty JSON array.");return r}function w(t,r){if(!Array.isArray(t)||0===t.length)throw new e("INVALID_ARGS","batch requires a non-empty batchSteps array.");if(t.length>r)throw new e("INVALID_ARGS",`batch has ${t.length} steps; max allowed is ${r}.`);let a=[];for(let r=0;r<t.length;r+=1){let i=t[r];if(!i||"object"!=typeof i)throw new e("INVALID_ARGS",`Invalid batch step at index ${r}.`);let n="string"==typeof i.command?i.command.trim().toLowerCase():"";if(!n)throw new e("INVALID_ARGS",`Batch step ${r+1} requires command.`);if(h.has(n))throw new e("INVALID_ARGS",`Batch step ${r+1} cannot run ${n}.`);if(void 0!==i.positionals&&!Array.isArray(i.positionals))throw new e("INVALID_ARGS",`Batch step ${r+1} positionals must be an array.`);let s=i.positionals??[];if(s.some(e=>"string"!=typeof e))throw new e("INVALID_ARGS",`Batch step ${r+1} positionals must contain only strings.`);if(void 0!==i.flags&&("object"!=typeof i.flags||Array.isArray(i.flags)||!i.flags))throw new e("INVALID_ARGS",`Batch step ${r+1} flags must be an object.`);if(void 0!==i.runtime&&("object"!=typeof i.runtime||Array.isArray(i.runtime)||!i.runtime))throw new e("INVALID_ARGS",`Batch step ${r+1} runtime must be an object.`);a.push({command:n,positionals:s,flags:i.flags??{},runtime:i.runtime})}return a}export{TextDecoder,styleText}from"node:util";export{p as DEFAULT_BATCH_MAX_STEPS,l as SETTINGS_INVALID_ARGS_MESSAGE,o as SETTINGS_USAGE_OVERRIDE,c as buildSnapshotDisplayLines,m as displayLabel,d as formatRole,u as formatSnapshotLine,f as parseBatchStepsJson,w as validateAndNormalizeBatchSteps};

package/dist/src/daemon/handlers/interaction-fill.d.ts

@@ -1,3 +0,0 @@
-import type { DaemonResponse } from '../types.ts';
-import type { InteractionHandlerParams } from './interaction-common.ts';
-export declare function handleFillCommand(params: InteractionHandlerParams): Promise<DaemonResponse>;

package/dist/src/daemon/handlers/interaction-press.d.ts

@@ -1,3 +0,0 @@
-import type { DaemonResponse } from '../types.ts';
-import type { InteractionHandlerParams } from './interaction-common.ts';
-export declare function handlePressCommand(params: InteractionHandlerParams): Promise<DaemonResponse>;

package/skills/agent-device/references/batching.md

@@ -1,79 +0,0 @@
-# Batching
-
-## When to use batch
-
-- The agent already knows a short sequence of commands.
-- Steps belong to one logical screen flow.
-- You want one result object with per-step timing and failure context.
-
-## When not to use batch
-
-- Flows are unrelated and should be retried independently.
-- The workflow is highly dynamic and requires replanning after each step.
-- You need human approvals between steps.
-
-## CLI patterns
-
-From file:
-
-```bash
-agent-device batch --session sim --platform ios --steps-file /tmp/batch-steps.json --json
-```
-
-Inline (small payloads only):
-
-```bash
-agent-device batch --steps '[{"command":"open","positionals":["settings"]}]'
-```
-
-## Step payload contract
-
-```json
-[
-  { "command": "open", "positionals": ["settings"], "flags": {} },
-  { "command": "wait", "positionals": ["label=\"Privacy & Security\"", "3000"], "flags": {} },
-  { "command": "click", "positionals": ["label=\"Privacy & Security\""], "flags": {} },
-  { "command": "get", "positionals": ["text", "label=\"Tracking\""], "flags": {} }
-]
-```
-
-Rules:
-
-- `positionals` optional, defaults to `[]`.
-- `flags` optional, defaults to `{}`.
-- nested `batch` and `replay` are rejected.
-- stop-on-first-error is the supported mode (`--on-error stop`).
-
-## Response handling
-
-Success includes:
-
-- `total`, `executed`, `totalDurationMs`
-- `results[]` entries with `step`, `command`, `durationMs`, and optional `data`
-
-Failure includes:
-
-- `details.step`
-- `details.command`
-- `details.executed`
-- `details.partialResults`
-
-Use these fields to replan from the first failing step.
-
-## Common error categories and agent actions
-
-- `INVALID_ARGS`: payload/step shape issue; fix payload and retry.
-- `SESSION_NOT_FOUND`: open or select the correct session, then retry.
-- `UNSUPPORTED_OPERATION`: switch command/target to supported operation.
-- `AMBIGUOUS_MATCH`: refine selector/locator, then retry failed step.
-- `COMMAND_FAILED`: add sync guard (`wait`, `is exists`) and retry from failed step.
-
-## Reliability guardrails
-
-- Add sync guards after mutating steps.
-- Assume snapshot/ref drift after navigation.
-- Keep batch size moderate (about 5-20 steps).
-- Split long workflows into phases:
-  1. navigate
-  2. verify/extract
-  3. cleanup

package/skills/agent-device/references/logs-and-debug.md

@@ -1,113 +0,0 @@
-# Logs (Token-Efficient Debugging)
-
-Logging is off by default in normal flows. Enable it on demand for debugging windows. App output is written to a session-scoped file so agents can grep it instead of loading full logs into context.
-`network dump` parses recent HTTP(s) entries from this same session app log file.
-
-## Data Handling
-
-- Default app logs are stored under `~/.agent-device/sessions/<session>/app.log`.
-- Replay scripts saved with `--save-script` are written to the explicit path you provide.
-- Log files may contain sensitive runtime data; review before sharing and clean up when finished.
-- Use `AGENT_DEVICE_APP_LOG_REDACT_PATTERNS` to redact sensitive patterns at write time when needed.
-
-## Retention and Cleanup
-
-- Keep logging scoped to active debug windows (`logs clear --restart` before repro, `logs stop` after repro).
-- Prefer bounded inspection (`grep -n`, `tail -50`) instead of reading full logs into context.
-- Clear session logs when finished:
-  `agent-device logs clear`
-- Close session to stop background logging state:
-  `agent-device close`
-
-## Quick Flow
-
-```bash
-agent-device open MyApp --platform ios      # or --platform android
-agent-device logs clear --restart    # Preferred: stop stream, clear logs, and start streaming again
-agent-device network dump 25         # Parse latest HTTP(s) requests (method/url/status) from app.log
-agent-device logs path               # Print path, e.g. ~/.agent-device/sessions/default/app.log
-agent-device logs doctor             # Check tool/runtime readiness for current session/device
-agent-device logs mark "before tap"  # Insert a timeline marker into app.log
-# ... run flows; on failure, grep the path (see below)
-agent-device logs stop               # Stop streaming (optional; close also stops)
-```
-
-Precondition: `logs clear --restart` requires an active app session (`open <app>` first).
-
-## Command Notes
-
-- `logs path`: returns log file path and metadata (`active`, `state`, `backend`, size, timestamps).
-- `logs start`: starts streaming; requires an active app session (`open` first). Supported on iOS simulator, iOS device, and Android.
-- `logs stop`: stops streaming. Session `close` also stops logging.
-- `logs clear`: truncates `app.log` and removes rotated `app.log.N` files. Requires logging to be stopped first.
-- `logs clear --restart`: convenience reset for repro loops (stop stream, clear files, restart stream).
-- `logs doctor`: reports backend/tool checks and readiness notes for troubleshooting.
-- `logs mark`: writes a timestamped marker line to the session log.
-- `network dump [limit] [summary|headers|body|all]`: parses recent HTTP(s) lines from the session app log and returns request summaries.
-- `network log ...`: alias for `network dump`.
-
-## Behavior and Limits
-
-- `logs start` appends to `app.log` and rotates to `app.log.1` when `app.log` exceeds 5 MB.
-- `network dump` scans the last 4000 app-log lines, returns up to 200 entries, and truncates payload/header fields at 2048 characters.
-- Android log streaming automatically rebinds to the app PID after process restarts.
-- iOS log capture relies on Unified Logging signals (for example `os_log`); plain stdout/stderr output may be limited depending on app/runtime.
-- Retention knobs:
-  - `AGENT_DEVICE_APP_LOG_MAX_BYTES`
-  - `AGENT_DEVICE_APP_LOG_MAX_FILES`
-- Optional write-time redaction patterns:
-  - `AGENT_DEVICE_APP_LOG_REDACT_PATTERNS` (comma-separated regex)
-
-## Grep Patterns
-
-After getting the path from `logs path`, run `grep` (or `grep -E`) so only matching lines enter context.
-
-```bash
-# Get path first, then grep it; -n adds line numbers
-grep -n "Error\|Exception\|Fatal" <path>
-grep -n -E "Error|Exception|Fatal|crash" <path>
-
-# Bounded context: last N lines only
-tail -50 <path>
-```
-
-- Use `-n` for line numbers.
-- Use `-E` for extended regex so `|` in the pattern does not need escaping.
-- Prefer targeted patterns (e.g. `Error`, `Exception`, or app-specific tags) over reading the full file.
-
-## Crash Triage Fast Path
-
-Always start from the session app log, then branch by platform.
-
-```bash
-agent-device logs path
-grep -n -E "SIGABRT|SIGSEGV|EXC_|fatal|exception|terminated|killed|jetsam|memorystatus|FATAL EXCEPTION|Abort message" <path>
-nl -ba <path> | sed -n '<start>,<end>p'
-```
-
-### iOS
-
-```bash
-# If log shows ReportCrash / SIGABRT / EXC_*, inspect simulator DiagnosticReports:
-ls -lt ~/Library/Logs/DiagnosticReports | grep -E "<AppName>|<BundleId>" | head
-```
-
-- `SIGABRT`: app/runtime abort; inspect `.ips` triggered thread and top frames.
-- `SIGKILL` + jetsam/memorystatus markers: memory-pressure kill.
-- `EXC_BAD_ACCESS`/`SIGSEGV`: native memory access issue.
-
-### Android
-
-```bash
-# Capture fatal crash lines around app process death:
-adb -s <serial> logcat -d | grep -n -E "FATAL EXCEPTION|Process: <package>|Abort message|signal [0-9]+ \\(SIG"
-```
-
-- `FATAL EXCEPTION` with Java stack: uncaught Java/Kotlin exception.
-- `signal 6 (SIGABRT)` or `signal 11 (SIGSEGV)` with tombstone refs: native crash path (NDK/JNI/runtime).
-- `Low memory killer` / `Killing <pid>` entries: OS memory-pressure/process reclaim.
-
-## Stop Conditions
-
-- If no crash signature appears in app log, switch to platform-native crash sources (`.ips` on iOS, logcat/tombstone flow on Android).
-- If signatures are present and root cause class is identified (abort, native fault, memory pressure), stop collecting broad logs and focus on reproducing the specific path.

package/skills/agent-device/references/perf-metrics.md

@@ -1,53 +0,0 @@
-# Performance Metrics (`perf` / `metrics`)
-
-Use this reference when you need to measure launch performance in agent workflows.
-
-## Quick flow
-
-```bash
-agent-device open Settings --platform ios
-agent-device perf --json
-```
-
-Alias:
-
-```bash
-agent-device metrics --json
-```
-
-## What is measured today
-
-- Session-scoped `startup` timing only.
-- Sampling method: `open-command-roundtrip`.
-- Unit: milliseconds (`ms`).
-- Source: elapsed wall-clock time around each session `open` command dispatch for the active app target.
-
-## Output fields to use
-
-- `metrics.startup.lastDurationMs`: most recent startup sample.
-- `metrics.startup.lastMeasuredAt`: ISO timestamp of most recent sample.
-- `metrics.startup.sampleCount`: number of retained samples.
-- `metrics.startup.samples[]`: recent startup history for the current session.
-- `sampling.startup.method`: current sampling method identifier.
-
-## Platform support (current)
-
-- iOS simulator: supported for startup sampling.
-- iOS physical device: supported for startup sampling.
-- Android emulator/device: supported for startup sampling.
-- `fps`, `memory`, and `cpu`: currently placeholders (`available: false`).
-
-## Interpretation guidance
-
-- Treat startup values as command round-trip timing, not true app first-frame or first-interactive telemetry.
-- Compare like-for-like runs:
-  - same device target
-  - same app build
-  - same workflow/session steps
-- Use multiple runs and compare trend/median, not one-off samples.
-
-## Common pitfalls
-
-- Running `perf` before any `open` in the session yields no startup sample yet.
-- Comparing values across different devices/runtimes introduces large noise.
-- Interpreting current `startup` as CPU/FPS/memory would be incorrect.

package/skills/agent-device/references/permissions.md

@@ -1,70 +0,0 @@
-# Permissions and Setup
-
-## iOS snapshots
-
-iOS snapshots use XCTest and do not require macOS Accessibility permissions.
-
-## iOS physical device runner
-
-For iOS physical devices, XCTest runner setup requires valid signing/provisioning.
-Use Automatic Signing in Xcode, or provide optional overrides:
-
-- `AGENT_DEVICE_IOS_TEAM_ID`
-- `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
-- `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
-- `AGENT_DEVICE_IOS_BUNDLE_ID` (optional runner bundle-id base override)
-
-Free Apple Developer (Personal Team) accounts may reject generic bundle IDs as unavailable.
-Set `AGENT_DEVICE_IOS_BUNDLE_ID` to a unique reverse-DNS identifier when that happens.
-
-Security guidance for these overrides:
-
-- These variables are optional and only needed for physical-device XCTest setup.
-- Treat values as sensitive host configuration; do not share in chat logs or commit to source control.
-- Do not provide private keys or unrelated secrets; use the minimum values required for signing.
-- Prefer Xcode Automatic Signing when possible to reduce manual secret/config handling.
-- For autonomous/CI runs, keep these unset by default and require explicit opt-in for physical-device workflows.
-
-If setup/build takes long, increase:
-
-- `AGENT_DEVICE_DAEMON_TIMEOUT_MS` (default `90000`, for example `120000`)
-
-If daemon startup fails with stale metadata hints, clean stale files and retry:
-
-- `~/.agent-device/daemon.json`
-- `~/.agent-device/daemon.lock`
-
-## iOS permission alerts (simulator only)
-
-iOS apps trigger system permission dialogs (camera, location, notifications, etc.) on first use.
-Use `alert` to handle them without tapping coordinates:
-
-```bash
-agent-device alert wait          # block until an alert appears (default 10 s timeout)
-agent-device alert accept        # accept the frontmost alert
-agent-device alert dismiss       # dismiss the frontmost alert
-agent-device alert get           # read alert title/message without acting
-```
-
-**Timing note:** `alert accept` and `alert dismiss` include a built-in 2 s retry window.
-If the alert is present in the UI hierarchy but not yet interactive, the command retries every 300 ms
-rather than failing immediately. You do not need to add manual sleeps between triggering the alert
-and accepting it.
-
-**Preferred pattern for clean simulator sessions:**
-
-```bash
-agent-device open MyApp --platform ios
-agent-device alert wait 5000     # wait up to 5 s for the permission prompt
-agent-device alert accept        # accept; retries internally if not yet actionable
-```
-
-`alert` is only supported on iOS simulators; iOS physical devices are not supported.
-
-## iOS: "Allow Paste" dialog
-
-iOS 16+ shows an "Allow Paste" prompt when an app reads the system pasteboard. Under XCUITest (which `agent-device` uses), this prompt is suppressed by the testing runtime. Use `xcrun simctl pbcopy booted` to set clipboard content directly on the simulator instead.
-
-## Simulator troubleshooting
-
-- If snapshots return 0 nodes, restart Simulator and re-open the app.

package/skills/agent-device/references/session-management.md

@@ -1,101 +0,0 @@
-# Session Management
-
-## Named sessions
-
-```bash
-agent-device --session auth open Settings --platform ios
-agent-device --session auth snapshot -i
-```
-
-Sessions isolate device context. A device can only be held by one session at a time.
-
-## Best practices
-
-- Name sessions semantically.
-- Close sessions when done.
-- Use separate sessions for parallel work.
-- For orchestrated QA runs, prefer a pre-bound session/platform over repeating per-command selectors.
-- For remote tenant-scoped automation, run commands with:
-  `--tenant <id> --session-isolation tenant --run-id <id> --lease-id <id>`
-- In iOS sessions, use `open <app>`. `open <url>` opens deep links; on devices `http(s)://` opens Safari when no app is active, and custom schemes require an active app in the session.
-- In iOS sessions, `open <app> <url>` opens a deep link.
-- On iOS, `appstate` is session-scoped and requires a matching active session on the target device.
-- For dev loops where runtime state can persist (for example React Native Fast Refresh), use `open <app> --relaunch` to restart the app process in the same session.
-- Use `--save-script [path]` to record replay scripts on `close`; path is a file path and parent directories are created automatically.
-- Use `close --shutdown` on iOS simulators or Android emulators to shut down the target as part of session teardown, preventing resource leakage in multi-tenant or CI workloads.
-- For ambiguous bare `--save-script` values, prefer `--save-script=workflow.ad` or `./workflow.ad`.
-- For deterministic replay scripts, prefer selector-based actions and assertions.
-- Use `replay -u` to update selector drift during maintenance.
-
-## Session-bound automation
-
-Use this when an external orchestrator must keep every CLI call on the same session/device without a wrapper script.
-
-```bash
-export AGENT_DEVICE_SESSION=qa-ios
-export AGENT_DEVICE_PLATFORM=ios
-export AGENT_DEVICE_SESSION_LOCK=strip
-
-agent-device open MyApp --relaunch
-agent-device snapshot -i
-agent-device press @e3
-agent-device close
-```
-
-- `AGENT_DEVICE_SESSION` and `AGENT_DEVICE_PLATFORM` provide the default binding when `--session` and `--platform` are omitted.
-- A configured `AGENT_DEVICE_SESSION` enables lock policy enforcement by convention. The default mode is `reject`.
-- `--session-lock reject|strip` or `AGENT_DEVICE_SESSION_LOCK=reject|strip` controls whether conflicting selectors fail or are ignored.
-- The daemon enforces the same lock policy for CLI requests, typed client calls, and direct RPC commands.
-- Conflicts include explicit retargeting selectors such as `--platform`, `--target`, `--device`, `--udid`, `--serial`, `--ios-simulator-device-set`, and `--android-device-allowlist`.
-- `--session-locked`, `--session-lock-conflicts`, `AGENT_DEVICE_SESSION_LOCKED`, and `AGENT_DEVICE_SESSION_LOCK_CONFLICTS` remain supported as compatibility aliases.
-- Lock policy applies to nested `batch` steps too. If a step omits `platform`, it still inherits the parent batch `--platform` instead of being silently replaced by an environment default.
-
-Android emulator variant:
-
-```bash
-export AGENT_DEVICE_SESSION=qa-android
-export AGENT_DEVICE_PLATFORM=android
-
-agent-device reinstall MyApp /path/to/app-debug.apk --serial emulator-5554
-agent-device --session-lock reject open com.example.myapp --relaunch
-agent-device snapshot -i
-agent-device close --shutdown
-```
-
-## Scoped device isolation
-
-Use scoped discovery when sessions must not see host-global device lists.
-
-```bash
-agent-device devices --platform ios --ios-simulator-device-set /tmp/tenant-a/simulators
-agent-device devices --platform android --android-device-allowlist emulator-5554,device-1234
-```
-
-- Scope is applied before selectors (`--device`, `--udid`, `--serial`).
-- If selector target is outside scope, resolution fails with `DEVICE_NOT_FOUND`.
-- If the scoped iOS simulator set is empty (first-run), the error includes the set path and a suggested `xcrun simctl --set <path> create ...` command.
-- With iOS simulator-set scope enabled, iOS physical devices are not enumerated.
-- Environment equivalents:
-  - `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET` (compat: `IOS_SIMULATOR_DEVICE_SET`)
-  - `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST` (compat: `ANDROID_DEVICE_ALLOWLIST`)
-
-## Listing sessions
-
-```bash
-agent-device session list
-```
-
-iOS session entries include `device_udid` and `ios_simulator_device_set` (null when using the default set). Use these fields to confirm device routing in concurrent multi-session runs without additional `simctl` calls.
-
-## Replay within sessions
-
-```bash
-agent-device replay ./session.ad --session auth
-agent-device replay -u ./session.ad --session auth
-```
-
-## Tenant isolation note
-
-When session isolation is set to tenant mode, session namespace is scoped as
-`<tenant>:<session>`. For remote runs, allocate and maintain an active lease
-for the same tenant/run scope before executing tenant-isolated commands.

package/skills/agent-device/references/snapshot-refs.md

@@ -1,102 +0,0 @@
-# Snapshot Refs and Selectors
-
-## Purpose
-
-Refs are useful for discovery/debugging. For deterministic scripts, use selectors.
-For tap interactions, `press` is canonical; `click` is an equivalent alias.
-For host Mac desktop apps, pair this reference with [macos-desktop.md](macos-desktop.md) because context menus and native list/table structures need desktop-specific handling.
-
-## Snapshot
-
-```bash
-agent-device snapshot -i
-```
-
-Output:
-
-```
-Page: com.apple.Preferences
-App: com.apple.Preferences
-
-@e1 [ioscontentgroup]
-  @e2 [button] "Camera"
-  @e3 [button] "Privacy & Security"
-```
-
-## Using refs (discovery/debug)
-
-```bash
-agent-device press @e2
-agent-device fill @e5 "test"
-```
-
-On macOS, if actions live in a context menu, use:
-
-```bash
-agent-device click @e5 --button secondary --platform macos
-agent-device snapshot -i
-```
-
-## Using selectors (deterministic)
-
-```bash
-agent-device press 'id="camera_row" || label="Camera" role=button'
-agent-device fill 'id="search_input" editable=true' "test"
-agent-device is visible 'id="camera_settings_anchor"'
-```
-
-## Ref lifecycle
-
-Refs can become invalid when UI changes (navigation, modal, dynamic list updates).
-Re-snapshot after transitions if you keep using refs.
-
-## Scope snapshots
-
-Use `-s` to scope to labels/identifiers. This reduces size and speeds up results:
-
-```bash
-agent-device snapshot -i -s "Camera"
-agent-device snapshot -i -s @e3
-```
-
-## Diff snapshots (structural)
-
-Use `diff snapshot` when you need compact state-change visibility between nearby UI states:
-
-```bash
-agent-device snapshot -i           # First snapshot initializes baseline
-agent-device press @e5
-agent-device diff snapshot -i           # Shows +/− structural lines vs prior snapshot
-```
-
-Efficient pattern:
-
-- Initialize once at a stable point.
-- Mutate UI (`press`, `fill`, `swipe`).
-- Run `diff snapshot` after interactions to confirm expected change shape with bounded output.
-- Re-run full/scoped `snapshot` only when you need fresh refs for next step selection.
-
-## Troubleshooting
-
-- Ref not found: re-snapshot.
-- If `snapshot` returns 0 nodes, foreground app state or accessibility state may have changed. Re-open the app or retry after state is stable.
-- On macOS, use `snapshot --raw --platform macos` to distinguish collector filtering from truly missing AX content.
-
-## Stop Conditions
-
-- If refs are unstable after UI transitions, switch to selector-based targeting and stop investing in ref-only flows.
-
-## find click response
-
-`find "<query>" click --json` returns deterministic matched-target metadata:
-
-```json
-{ "ref": "@e3", "locator": "any", "query": "Increment", "x": 195, "y": 422 }
-```
-
-Fields come from the matched snapshot node, not the platform runner. Use these for observability and replay quality — they are stable across runs for the same UI state.
-
-## Replay note
-
-- Prefer selector-based actions in recorded `.ad` replays.
-- Use `agent-device replay -u <path>` to update selector drift and rewrite replay scripts in place.