agent-device 0.17.9 → 0.18.0

package/dist/src/batch.d.ts

@@ -12,6 +12,20 @@ export declare type BatchRequest = Omit<DaemonRequest, 'flags'> & {
     flags?: BatchFlags | Record<string, unknown>;
 };
 
+export declare type BatchRunResponse = {
+    ok: true;
+    data: BatchRunResult;
+} | Extract<DaemonResponse, {
+    ok: false;
+}>;
+
+export declare type BatchRunResult = Record<string, unknown> & {
+    total: number;
+    executed: number;
+    totalDurationMs: number;
+    results: BatchStepResult[];
+};
+
 export declare type BatchStepResult = {
     step: number;
     command: string;
@@ -36,7 +50,7 @@ export declare type DaemonBatchStep = {
     command: string;
     positionals?: string[];
     flags?: Record<string, unknown>;
-    runtime?: unknown;
+    runtime?: DaemonRequest['runtime'];
 };
 
 declare type DaemonError = {
@@ -90,6 +104,9 @@ declare type DaemonRequestMeta = {
     leaseId?: string;
     leaseTtlMs?: number;
     leaseBackend?: LeaseBackend;
+    leaseProvider?: string;
+    deviceKey?: string;
+    clientId?: string;
     sessionIsolation?: SessionIsolationMode;
     uploadedArtifactId?: string;
     clientArtifactPaths?: Record<string, string>;
@@ -126,14 +143,14 @@ export declare type NormalizedBatchStep = {
     command: string;
     positionals: string[];
     flags: Record<string, unknown>;
-    runtime?: unknown;
+    runtime?: DaemonRequest['runtime'];
 };
 
 declare const PLATFORM_SELECTORS: readonly ["ios", "macos", "android", "linux", "web", "apple"];
 
 declare type PlatformSelector = (typeof PLATFORM_SELECTORS)[number];
 
-export declare function runBatch(req: BatchRequest, sessionName: string, invoke: BatchInvoke): Promise<DaemonResponse>;
+export declare function runBatch(req: BatchRequest, sessionName: string, invoke: BatchInvoke): Promise<BatchRunResponse>;
 
 declare const SESSION_ISOLATION_MODES: readonly ['none', 'tenant'];
 

package/dist/src/batch.js

@@ -1 +1 @@
-var _=100;export{BATCH_BLOCKED_COMMANDS,INHERITED_PARENT_FLAG_KEYS}from"./2133.js";export{buildBatchStepFlags,runBatch,validateAndNormalizeBatchSteps}from"./6918.js";export{_ as DEFAULT_BATCH_MAX_STEPS};
+var _=100;export{BATCH_BLOCKED_COMMANDS,INHERITED_PARENT_FLAG_KEYS}from"./5341.js";export{buildBatchStepFlags,runBatch,validateAndNormalizeBatchSteps}from"./6918.js";export{_ as DEFAULT_BATCH_MAX_STEPS};

package/dist/src/cli-help.js

@@ -1,4 +1,4 @@
-import{listCliCommandNames as e}from"./2133.js";import{getCliCommandSchema as t,getCommandSchema as o}from"./9581.js";import{getFlagDefinitions as a,GLOBAL_FLAG_KEYS as s}from"./2948.js";let n=[{label:"help workflow",description:"Normal bootstrap, exploration, and validation loop"},{label:"help debugging",description:"Logs, network, perf memory, and traces"},{label:"help react-native",description:"React Native app automation hazards, overlays, Metro, and routing"},{label:"help react-devtools",description:"React Native performance, profiling, component tree, and renders"},{label:"help physical-device",description:"Connected phone/tablet setup and iOS signing prerequisites"},{label:"help remote",description:"Remote/cloud config, tenants, leases, and local service tunnels"},{label:"help web",description:"Minimal browser sessions through agent-browser"},{label:"help macos",description:"Desktop, frontmost-app, and menu bar surfaces"},{label:"help dogfood",description:"Exploratory QA report workflow"}],r=["Planning output contract: when asked to plan commands, output command lines only: no prose, numbering, Markdown fences, pipes, or shell helpers.","Default loop: devices/apps -> open -> snapshot -i -> press/fill/get/is/wait/find -> verify -> close.",'Use selectors or refs as positional targets: id="submit", label="Allow", or @e12 from snapshot -i.',"Plain snapshot reads state; snapshot -i refreshes current interactive refs only.","Default snapshot text is an agent-facing, token-efficient view for planning and targeting actions.","Read-only visible/state question: use snapshot/get/is/find; use snapshot -i only when refs are needed.","Anti-pattern: snapshot -i followed by snapshot -i | grep ...; prior refs stay valid until app state changes, and --force-full is the explicit full re-read.","Truncated text/input preview: expand first with snapshot -s @e12, not get text.","React Native apps: read help react-native for Metro, DevTools routing, and RN-specific blockers; use react-native dismiss-overlay for LogBox/RedBox overlays.","Android RN/Expo Metro: direct Android localhost URL opens with a port auto-configure host reachability.",'Expo Go/dev clients: use the provided URL when given; on iOS use open "Expo Go" <url> --platform ios, then snapshot -i --platform ios to verify project UI. Do not use plain snapshot or snapshot --diff for this recovery check. Android URL opens infer the foreground package for logs/perf when possible.',"Install flows: install/install-from-source first, then open the installed id with --relaunch.",'Text: fill \'id="field-email"\' "qa@example.com" replaces; type appends after press.','Clearing text: do not use fill <target> ""; use a visible clear/reset control or report that clearing is unsupported.',"Android IME capture: if fill says input was captured by the keyboard/IME, inspect keyboard state and switch/disable handwriting before retrying; do not loop fill/type.","Implicit default sessions are scoped to the current worktree; if a prompt names a Session, include --session <name> on every command in that flow.","Run mutating commands serially within one session; parallelize only read-only commands or separate sessions/devices.","Clipboard limits: iOS Allow Paste cannot be automated through XCUITest; prefill with clipboard write. Android non-ASCII should use fill/type, not raw adb input.","After mutation: refs are stale. If the next target is known, use its selector directly; otherwise refresh with snapshot -i, scoped with -s when a stable container is known. Do not use tap; use press or click.","Raw coordinates are fallback-only: use snapshot -i --json rects when iOS refs no-op or child refs are missing, then verify the action with diff snapshot -i or snapshot --diff.","Sparse or AX-unavailable snapshot: use screenshot for visual truth, press the visible coordinate to leave the bad screen, then retry AX with snapshot -i.","macOS context menus use click <ref> --button secondary, then snapshot -i. Longpress is for mobile hold gestures, not macOS secondary-click menus.","Remote workflow profiles use --remote-config on operational commands. Do not substitute --config; --config only loads CLI defaults.",'Batch JSON steps use "command" and structured "input"; legacy "positionals"/"flags" steps still run in CLI but are deprecated until the next major version.',"Navigation: app-owned back uses back; system back uses back --system.","Web browser sessions: read help web; first slice is web setup if needed -> web doctor -> open <url> --platform web -> snapshot -i -> click/fill/get/is/find/wait/screenshot -> close.","Verification commands must name the expected text/selector; bare screenshots/snapshots are not enough.","Debug evidence: Session state contains request diagnostics and runner.log; use logs clear --restart/mark/path, trace, and network dump --include headers for app evidence.","Use agent-device commands in final plans; raw platform tools, pseudo commands, and helper prose are wrong.","Full operating guide: agent-device help workflow. Exploratory QA: agent-device help dogfood."],i=["Default config files: ~/.agent-device/config.json, ./agent-device.json","Use --config <path> or AGENT_DEVICE_CONFIG to load one explicit config file."],c=[{label:"AGENT_DEVICE_SESSION",description:"Explicit session name"},{label:"AGENT_DEVICE_PLATFORM",description:"Default platform binding"},{label:"AGENT_DEVICE_SESSION_LOCK",description:"Bound-session conflict mode"},{label:"AGENT_DEVICE_DAEMON_BASE_URL",description:"Connect to remote daemon"},{label:"AGENT_DEVICE_DAEMON_AUTH_TOKEN",description:"Remote daemon service/API token"},{label:"AGENT_DEVICE_CLOUD_BASE_URL",description:"Bridge/control-plane API origin for cloud auth and /api-keys"}],l=["agent-device open Settings --platform ios","agent-device open https://example.com --platform web","agent-device open TextEdit --platform macos","agent-device snapshot -i","agent-device react-devtools get tree --depth 3",'agent-device fill @e3 "test@example.com"',"agent-device replay ./session.ad","agent-device test ./suite --platform android"],d={workflow:{summary:"Normal agent-device bootstrap, exploration, and validation loop",body:`agent-device help workflow
+import{listCliCommandNames as e}from"./5341.js";import{getCliCommandSchema as t,getCommandSchema as a}from"./9581.js";import{getFlagDefinitions as o,GLOBAL_FLAG_KEYS as s}from"./2948.js";let n=[{label:"agent-device help workflow",description:"Start here for the core loop, command shape, refs/selectors, and verification"},{label:"agent-device help debugging",description:"Use when logs, network, perf memory, traces, alerts, or diagnostics matter"},{label:"agent-device help react-native",description:"Use when the target app is React Native, Expo, or a dev client"},{label:"agent-device help react-devtools",description:"Use when inspecting components, props/state/hooks, renders, or profiles"},{label:"agent-device help cdp",description:"Use when investigating JS heap growth, heap snapshots, or retainers"},{label:"agent-device help physical-device",description:"Use when using a connected phone/tablet or iOS signing setup"},{label:"agent-device help remote",description:"Use when working through cloud config, tenants, leases, or local tunnels"},{label:"agent-device help web",description:"Use when automating a browser through agent-device sessions"},{label:"agent-device help macos",description:"Use when targeting desktop, frontmost app, or menu bar surfaces"},{label:"agent-device help dogfood",description:"Use when producing exploratory QA evidence"}],r=["agent-device is the default automation surface for app/device workflows across supported targets.","Default to agent-device for installs, opens, snapshots, interactions, screenshots, logs, network/perf evidence, and verification.","Use raw adb, simctl, xcrun, or platform scripts only when this help calls out a tool gap or platform setup step.","Start with agent-device help workflow to understand the core loop and how to use the tool."],i=["Planning output contract: when asked to plan commands, output command lines only: no prose, numbering, Markdown fences, pipes, or shell helpers.","Default loop: devices/apps -> open -> snapshot -i -> press/fill/get/is/wait/find -> verify -> close.",'Use selectors or refs as positional targets: id="submit", label="Allow", or @e12 from snapshot -i.',"Plain snapshot reads state; snapshot -i refreshes current interactive refs only.","Default snapshot text is an agent-facing, token-efficient view for planning and targeting actions.","Read-only visible/state question: use snapshot/get/is/find; use snapshot -i only when refs are needed.","Anti-pattern: snapshot -i followed by snapshot -i | grep ...; prior refs stay valid until app state changes, and --force-full is the explicit full re-read.","Truncated text/input preview: expand first with snapshot -s @e12, not get text.","React Native apps: read help react-native for Metro, DevTools routing, and RN-specific blockers; use react-native dismiss-overlay for LogBox/RedBox overlays.","React Native JS memory leaks: read help cdp; use heap usage samples for a quick signal, then snapshot diff/leak-triplet for retained object proof.","Android RN/Expo Metro: direct Android localhost URL opens with a port auto-configure host reachability.",'Expo Go/dev clients: use the provided URL when given; on iOS use open "Expo Go" <url> --platform ios, then snapshot -i --platform ios to verify project UI. Do not use plain snapshot or snapshot --diff for this recovery check. Android URL opens infer the foreground package for logs/perf when possible.',"Install flows: install/install-from-source first, then open the installed id with --relaunch.",'Text: fill \'id="field-email"\' "qa@example.com" replaces; type appends after press.','Clearing text: do not use fill <target> ""; use a visible clear/reset control or report that clearing is unsupported.',"Android IME capture: if fill says input was captured by the keyboard/IME, inspect keyboard state and switch/disable handwriting before retrying; do not loop fill/type.","Implicit default sessions are scoped to the current worktree; if a prompt names a Session, include --session <name> on every command in that flow.","Run mutating commands serially within one session; parallelize only read-only commands or separate sessions/devices.","Clipboard limits: iOS Allow Paste cannot be automated through XCUITest; prefill with clipboard write. Android non-ASCII should use fill/type, not raw adb input.","After mutation: refs are stale. If the next target is known, use its selector directly; otherwise refresh with snapshot -i, scoped with -s when a stable container is known. Do not use tap; use press or click.","Raw coordinates are fallback-only: use snapshot -i --json rects when iOS refs no-op or child refs are missing, then verify the action with diff snapshot -i or snapshot --diff.","Sparse or AX-unavailable snapshot: use screenshot for visual truth, press the visible coordinate to leave the bad screen, then retry AX with snapshot -i.","macOS context menus use click <ref> --button secondary, then snapshot -i. Longpress is for mobile hold gestures, not macOS secondary-click menus.","Remote lifecycle: use connect, then open, commands, close, and disconnect. Cloud, remote-config, direct proxy, and limrun use the same flow.","Direct proxy: run agent-device connect proxy --daemon-base-url <proxy-agent-device-url> before using a shared Mac proxy. Device leases are automatic on open and expire after five minutes of inactivity.",'Batch JSON steps use "command" and structured "input"; legacy "positionals"/"flags" steps still run in CLI but are deprecated until the next major version.',"Navigation: app-owned back uses back; system back uses back --system.","Web browser sessions: read help web; first slice is web setup if needed -> web doctor -> open <url> --platform web -> snapshot -i -> click/fill/get/is/find/wait/screenshot -> close.","Verification commands must name the expected text/selector; bare screenshots/snapshots are not enough.","Debug evidence: Session state contains request diagnostics and runner.log; use logs clear --restart/mark/path, trace, and network dump --include headers for app evidence.","Full operating guide: agent-device help workflow. Exploratory QA: agent-device help dogfood."],c=["Default config files: ~/.agent-device/config.json, ./agent-device.json","Use --config <path> or AGENT_DEVICE_CONFIG to load one explicit config file."],d=[{label:"AGENT_DEVICE_SESSION",description:"Explicit session name"},{label:"AGENT_DEVICE_PLATFORM",description:"Default platform binding"},{label:"AGENT_DEVICE_SESSION_LOCK",description:"Bound-session conflict mode"},{label:"AGENT_DEVICE_DAEMON_BASE_URL",description:"Connect to remote daemon"},{label:"AGENT_DEVICE_DAEMON_AUTH_TOKEN",description:"Remote daemon service/API token"},{label:"AGENT_DEVICE_CLOUD_BASE_URL",description:"Bridge/control-plane API origin for cloud auth and /api-keys"}],l=["agent-device open Settings --platform ios","agent-device open https://example.com --platform web","agent-device open TextEdit --platform macos","agent-device snapshot -i","agent-device react-devtools get tree --depth 3","agent-device cdp memory usage sample --gc --label baseline",'agent-device fill @e3 "test@example.com"',"agent-device replay ./session.ad","agent-device test ./suite --platform android"],p={workflow:{summary:"Normal agent-device bootstrap, exploration, and validation loop",body:`agent-device help workflow
 
 Version-matched operating guide for normal agent-device work.
 
@@ -28,7 +28,7 @@ Bootstrap:
   agent-device prepare ios-runner --platform ios --timeout 240000
   If app id is unknown, plan devices, apps, then open <discovered-app-id>. Discovery is not enough when the task asks to open/start the app.
   Install arguments are app/package id then artifact path. If the task says install, use install; use reinstall only when explicitly requested. Fresh runtime state is open --relaunch after install.
-  In Apple CI, run prepare ios-runner after boot/install and before replay/test. prepare ios-runner builds/reuses the XCTest runner, health-checks it with a lightweight command, and retries one stuck/non-connecting runner launch before the first snapshot pays that setup cost. If the replay/test step starts a separate daemon, run clean:daemon after prepare so the prepared runner does not keep a live lease owned by the prepare daemon.
+  In Apple CI, run prepare ios-runner after boot/install and before replay/test. prepare ios-runner builds/reuses the XCTest runner, health-checks it with a lightweight command, and retries one stuck/non-connecting runner launch before the first snapshot pays that setup cost. It is not a recovery step for "runner already owned by another agent-device daemon"; stop or clean the owning daemon on the Mac with simulator access instead. If the replay/test step starts a separate daemon, run clean:daemon after prepare so the prepared runner does not keep a live lease owned by the prepare daemon.
   CI may cache ~/.agent-device/ios-runner/derived with an exact key that includes the agent-device package and Xcode version. Avoid broad restore-key fallbacks; prepare ios-runner already recovers bad restored runner artifacts and one retryable non-connecting runner launch. Runner build/start output is written to the session's runner.log; daemon.log is for daemon lifecycle/startup issues.
   Do not open artifact paths or invent package ids. If apps lookup misses the target and no URL/artifact is provided, ask or stop.
 
@@ -140,7 +140,9 @@ Validation and evidence:
   Android animations: settings animations off/on, not animations disable/restore.
   Debug logs: logs clear --restart, logs mark, reproduce, then logs path; do not split clear/restart into separate stop/start commands.
   Network headers: network dump --include headers; do not write network log headers.
-  Remote/cloud: connect to discover a cloud profile, or connect --remote-config ./remote-config.json for a local profile; then open, snapshot, disconnect.
+  Remote lifecycle: cloud, remote-config, direct proxy, and limrun use the same flow: connect, open, commands, close, disconnect.
+  Remote config profile: agent-device connect --remote-config ./remote-config.json; then run normal commands and disconnect.
+  Direct proxy to a Mac you control: cloud/Linux clients can use local/proxy iOS devices through the proxied Mac. Run agent-device connect proxy --daemon-base-url <proxy-agent-device-url> first. Device leases are automatic on open and expire after five minutes of inactivity.
   Web: agent-device uses a managed, pinned agent-browser backend as an implementation detail. Use --platform web when a browser step belongs inside an agent-device session, replay, batch, MCP, or typed-client flow; use agent-browser directly for standalone web automation. Run agent-device web setup before first use, then agent-device web doctor for backend health checks. Web automation requires Node 24+.
     agent-device web setup
     agent-device web doctor
@@ -152,12 +154,14 @@ Validation and evidence:
     agent-device click @e12 --platform web
     agent-device fill @e13 "qa@example.com" --platform web
     agent-device wait text "Welcome" 3000 --platform web
+    agent-device record start ./artifacts/web-flow.webm --platform web
     agent-device network dump 25 --include headers --platform web
     agent-device screenshot ./artifacts/web-home.png --platform web
     agent-device screenshot ./artifacts/web-full.png --platform web --fullscreen
     agent-device viewport 1280 900 --platform web
+    agent-device record stop --platform web
     agent-device close --platform web
-  Minimal web support is for browser sessions with open, snapshot, find, get, is, click/press, fill/type, wait, network dump, screenshot, close, and replay over those commands. Use agent-browser directly for browser-specific features that agent-device does not surface, such as tab/devtools management, advanced page scripting, network routing/HAR, or raw browser debugging.
+  Minimal web support is for browser sessions with open, snapshot, find, get, is, click/press, fill/type, wait, network dump, screenshot, record start/stop with WebM output, close, and replay over those commands. Use agent-browser directly for browser-specific features that agent-device does not surface, such as tab/devtools management, advanced page scripting, network routing/HAR, or raw browser debugging.
   macOS menu bar: open ... --platform macos --surface menubar; snapshot -i --platform macos --surface menubar.
   Maestro full-suite validation on explicit connected devices uses one test command with a comma-separated --device list and --shard-all. Use --shard-split only when splitting suite entries across devices:
     agent-device test ./e2e/maestro --maestro --device udid1,emulator-5554 --shard-all 2
@@ -343,7 +347,55 @@ Example:
   agent-device react-devtools profile report @c5
   agent-device network dump --include headers
 
-Use snapshot, screenshot, logs, network, and perf metrics for device/app runtime evidence. Use react-devtools only when component internals or React rendering behavior matters.`},"react-native":{summary:"React Native app automation hazards and routing",body:`agent-device help react-native
+Use snapshot, screenshot, logs, network, and perf metrics for device/app runtime evidence. Use react-devtools only when component internals or React rendering behavior matters.`},cdp:{summary:"React Native CDP targets, JS heap snapshots, and leak triage",body:`agent-device help cdp
+
+Use this when a React Native or Expo app exposes a CDP target through Metro and
+the task needs JavaScript heap growth checks, heap snapshot diffs, allocation
+hotspots, retained-object leak evidence, or a small runtime eval to confirm JS
+state. Do not use this as the default React Native profiler.
+
+Setup:
+  Start Metro and open the app first. For Android devices/emulators, make sure Metro is reachable from the app, typically with adb reverse tcp:8081 tcp:8081.
+  In remote bridge sessions, omit --url for target list/select after connect; agent-device derives the Metro CDP URL from the prepared remote runtime.
+  agent-device cdp target list --url http://127.0.0.1:8081
+  agent-device cdp target select <target-id>
+
+Quick JS heap signal:
+  agent-device cdp memory usage sample --label baseline --gc
+  # perform the suspected leaking action with agent-device commands
+  agent-device cdp memory usage sample --label after-action --gc
+  agent-device cdp memory usage diff --base jm_1 --compare jm_2
+  agent-device cdp memory usage leak-signal --since jm_1
+
+Retained-object proof:
+  agent-device cdp memory snapshot capture --name baseline --gc
+  # perform the suspected leaking action
+  agent-device cdp memory snapshot capture --name after-action --gc
+  # perform cleanup/navigation that should release the objects
+  agent-device cdp memory snapshot capture --name cleanup --gc
+  agent-device cdp memory snapshot diff --base ms_1 --compare ms_2 --limit 10
+  agent-device cdp memory snapshot leak-triplet --baseline ms_1 --action ms_2 --cleanup ms_3 --limit 10
+  agent-device cdp memory snapshot retainers --snapshot ms_3 --id <node-id> --depth 8 --limit 10
+
+Allocation pressure:
+  Use allocation sampling to find where allocations were created, not to prove a leak:
+    agent-device cdp memory allocation start --name suspected-flow --interval 32768 --stack-depth 32
+    # perform the flow once
+    agent-device cdp memory allocation stop
+    agent-device cdp memory allocation hotspots --limit 10
+    agent-device cdp memory allocation source-maps
+
+Recommended subset:
+  cdp dynamically runs a pinned CDP helper through npm; the first run may download the pinned package, and later runs can reuse the npm cache.
+  Every argument after cdp is passed to the CDP helper. Put agent-device global flags before cdp when you need the outer CLI to consume them.
+  Use cdp memory usage, memory snapshot, memory allocation, and targeted runtime eval.
+  Avoid cdp profile cpu, trace, network, and console by default because agent-device already has perf cpu, trace, network, logs, and react-devtools guidance for those areas.
+
+Output contract:
+  Until cdp has a compact leak report command, synthesize one from memory usage diff, snapshot diff, leak-triplet, and retainers. Report heap deltas, top retained classes/shapes, leak-triplet rows that stayed high after cleanup, and the shortest useful retaining paths. Do not paste raw heap snapshots or large allocation profiles into the response; use exported artifacts only when the user asks for raw data.
+
+Target caveats:
+  React Native/Hermes implements a subset of browser CDP. If a command reports an unsupported method, keep the target selected and switch to heap usage samples plus heap snapshots. Prefer react-devtools for component tree/render causes; prefer perf memory sample or perf memory snapshot for native/process memory.`},"react-native":{summary:"React Native app automation hazards and routing",body:`agent-device help react-native
 
 Use this when the target app is React Native, Expo, or a React Native dev client.
 This topic covers React Native-specific automation hazards and routes deeper
@@ -353,6 +405,7 @@ Choose the next help topic:
   Generic navigation, selectors, refs, verification, serial commands: help workflow.
   Logs, network, diagnostics, traces, permission dialogs, or runtime failures: help debugging.
   Component tree, props/state/hooks, slow renders, rerenders, or render causes: help react-devtools.
+  JS heap growth, heap snapshots, allocation hotspots, or retained-object leaks: help cdp.
   Remote/cloud config, leases, and local service tunnels: help remote.
 
 React Native dev loop:
@@ -361,7 +414,7 @@ React Native dev loop:
     agent-device metro reload
     agent-device find "Home"
   Do not use agent-device reload. Use open --relaunch for native startup reset.
-  Android RN/Expo Metro: direct Android localhost URL opens with a port auto-configure host reachability. For app/package launches, use help react-native if the app cannot reach local Metro.
+  Android RN/Expo Metro: direct Android localhost URL opens with a port auto-configure host reachability. For app/package launches, run metro prepare when the app cannot reach local Metro.
   Verify Metro from the same host context that owns Metro. If a sandboxed shell cannot curl localhost:8081/status but an unrestricted host shell can, Metro is running and the sandbox probe is not authoritative.
   adb reverse only affects Android device-to-host traffic. It does not prove host-to-Metro reachability, and it does not fix a redbox caused by a stale or wrong Metro/app state.
   Multiple local worktrees can reuse one native iOS simulator build by running each worktree's Metro on a different port and opening the same installed app on different simulators with explicit runtime hints:
@@ -400,6 +453,11 @@ React DevTools routing:
   Use help react-devtools for status/wait, component trees, props/state/hooks, profile windows, slow renders, rerenders, and remote bridge rules.
   If React DevTools cannot connect, report status and continue with logs, network, perf metrics, screenshot, and trace evidence instead of blocking the whole flow.
 
+CDP memory routing:
+  Keep the agent-device cdp prefix on every CDP command.
+  Use help cdp for JS heap usage samples, heap snapshots, snapshot diffs, leak-triplet analysis, allocation hotspots, and retained-object paths.
+  Use perf memory sample or perf memory snapshot for native/process memory; use cdp only for JavaScript heap evidence.
+
 Slow-flow investigation:
   Keep one session, open the app first, and snapshot -i before interacting.
   Start React Native slow-flow plans with this ordered scaffold:
@@ -438,9 +496,27 @@ iOS physical-device prerequisites:
 
 Android physical-device prerequisites:
   Enable USB debugging and confirm the device appears in agent-device devices --platform android.
-  Android does not need the iOS runner signing setup. For React Native/Expo Metro reachability, read help react-native.`},remote:{summary:"Remote config, tenant, lease, and remote host flow",body:`agent-device help remote
+  Android does not need the iOS runner signing setup. For React Native/Expo Metro reachability, read help react-native.`},remote:{summary:"Direct proxy, cloud profiles, and remote config",body:`agent-device help remote
+
+Remote connection providers use the same lifecycle:
+  connect -> open -> commands -> close -> disconnect
 
-Use remote config or the cloud connection profile when a profile owns daemon URL, auth, tenant, run, lease, device scope, and Metro hints. Do not restate those as individual flags unless overriding intentionally.
+Providers:
+  Cloud: agent-device connect discovers the cloud profile.
+  Remote config: agent-device connect --remote-config ./remote-config.json uses a local profile.
+  Direct proxy: agent-device connect proxy --daemon-base-url <proxy-agent-device-url> stores the shared proxy profile and client identity.
+
+Direct proxy flow for a remote Mac/simulator:
+  On the Mac with simulator/device access:
+    agent-device proxy --port 4310
+    cloudflared tunnel --url http://127.0.0.1:4310
+  On the remote client:
+    agent-device connect proxy --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token <token>
+    agent-device devices --platform ios
+    agent-device open Maps --platform ios --device "iPhone 17 Pro"
+    agent-device snapshot -i --platform ios --device "iPhone 17 Pro"
+    agent-device close
+    agent-device disconnect
 
 Cloud profile flow:
   agent-device connect
@@ -459,21 +535,17 @@ Script flow, per-command config:
   agent-device snapshot --remote-config ./remote-config.json
   agent-device disconnect --remote-config ./remote-config.json
 
-Direct proxy flow for a remote Mac:
-  On the Mac with simulator/device access:
-    agent-device proxy --port 4310
-    cloudflared tunnel --url http://127.0.0.1:4310
-  On the remote client:
-    agent-device devices --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token <token>
-    agent-device devices
-
 Rules:
   connect and disconnect are top-level commands. Do not write agent-device remote connect or agent-device remote disconnect.
   Use connect without --remote-config when the cloud control plane owns the connection profile.
-  Prefer --remote-config over --daemon-base-url, --tenant, --run-id, and --lease-id when using a local profile.
-  Use agent-device proxy for direct tunnel access to a Mac you control. Copy the printed daemon base URL and daemon auth token; do not use agent-device auth for this direct proxy flow.
-  For repeated direct proxy commands, store daemonBaseUrl and daemonAuthToken in normal agent-device.json CLI config. Keep platform selection on each command or workflow. Do not use --remote-config unless you are using the tenant/run/lease remote connection flow.
+  Prefer connect --remote-config over --daemon-base-url, --tenant, --run-id, and --lease-id when using a local profile.
+  Use agent-device proxy for direct tunnel access to a Mac you control. Expose the printed proxy URL through cloudflared/ngrok, then run agent-device connect proxy with the tunnel URL and printed token before normal commands.
+  connect proxy stores the connection profile and client identity. Device leases are acquired on open and expire after five minutes without commands.
+  Multiple agents can share one proxy when each uses connect proxy, open, commands, close, and disconnect.
+  disconnect releases local connection state; close releases the active session and device lease.
+  A busy direct-proxy device error means another agent owns the device until it closes or its inactivity lease expires.
   Keep the proxy token secret. Anyone with the token can control the proxied daemon.
+  If local/proxy iOS reports that the runner is already owned by another agent-device daemon after lease admission, retry after the owning session closes or after lease expiry. If the conflict repeats, clean stale daemon state on the machine with simulator access.
   Do not use --config as a remote profile flag. --config loads CLI defaults; --remote-config selects remote daemon/profile settings.
   For self-contained scripts, pass the same --remote-config to every operational command, including disconnect; a preceding connect is optional but not required.
   For remote artifact installs, use install-from-source <url> or install-from-source --github-actions-artifact org/repo:artifact; do not download CI artifacts locally first.
@@ -533,14 +605,16 @@ First-slice loop:
   agent-device click @e12 --platform web
   agent-device fill @e13 "qa@example.com" --platform web
   agent-device wait text "Welcome" 3000 --platform web
+  agent-device record start ./artifacts/web-flow.webm --platform web
   agent-device network dump 25 --include headers --platform web
   agent-device screenshot ./artifacts/web-home.png --platform web
   agent-device screenshot ./artifacts/web-full.png --platform web --fullscreen
   agent-device viewport 1280 900 --platform web
+  agent-device record stop --platform web
   agent-device close --platform web
 
 Supported in agent-device web sessions:
-  open <url>, snapshot -i, get text/attrs, is visible/exists/text, find text/selector, click/press @ref or selector, fill/type @ref or selector, wait text/selector, network dump, screenshot, close, and replay scripts made from those commands.
+  open <url>, snapshot -i, get text/attrs, is visible/exists/text, find text/selector, click/press @ref or selector, fill/type @ref or selector, wait text/selector, network dump, screenshot, record start/stop with WebM output, close, and replay scripts made from those commands.
 
 Out of scope for agent-device web support:
   Browser runtime debugging, tabs/windows/devtools control, network routing/interception/HAR, storage/cookie management, arbitrary page scripting, downloads/uploads, multi-page orchestration, and agent-browser-specific diagnostics. Use agent-browser directly for those browser-specific workflows.
@@ -605,37 +679,39 @@ Rules:
   Prefer refs for exploration and selectors for deterministic replay.
   Use logs, network, screenshot --overlay-refs, trace, perf metrics, perf frames, or react-devtools only when they add evidence to a specific issue.
   Never delete screenshots, videos, traces, or report artifacts during a session.
-  Escalate to help debugging or help react-devtools when runtime symptoms require those tools.`}};function p(e){let t=e.endsWith("?"),o=t?e.slice(0,-1):e;return t?`[${o}]`:`<${o}>`}function u(){let o,a,d,p,u,v,b,w;return o=`agent-device <command> [args] [--json]
+  Escalate to help debugging or help react-devtools when runtime symptoms require those tools.`}};function h(e){let t=e.endsWith("?"),a=t?e.slice(0,-1):e;return t?`[${a}]`:`<${a}>`}function u(){let a,o,p,h,u,b,w,y,k;return a=`agent-device <command> [args] [--json]
+
+CLI to automate supported app, device, desktop, and web targets for AI agents.
+`,o=g("Commands:",e().map(e=>{let a=t(e);return{name:e,schema:a,usage:function(e,t){if(t.listUsageOverride)return t.listUsageOverride;let a=(t.positionalArgs??[]).map(a=>{var o,s,n;let r,i,c,d;return o=e,s=t,i=(r=(n=a).endsWith("?"))?n.slice(0,-1):n,d=(c=/^[a-z-]+(?:\|[a-z-]+)+$/i.test(i))||void 0!==s.usageOverride&&s.usageOverride.startsWith(`${o} ${i}`),r?c?`[${i}]`:d?i:`[${i}]`:d?i:`<${i}>`});return[e,...a].join(" ")}(e,a)}}).map(e=>({label:e.usage,description:e.schema.summary??e.schema.helpDescription}))),p=f("Global Flags:",m(s)),h=v("Agent Starting Point:",r),u=v("Agent Quickstart:",i),b=g("Agent Workflows:",n),w=v("Configuration:",c),y=g("Environment:",d),k=v("Examples:",l),`${a}
+${h}
 
-CLI to control iOS and Android devices for AI agents.
-`,a=m("Commands:",e().map(e=>{let o=t(e);return{name:e,schema:o,usage:function(e,t){if(t.listUsageOverride)return t.listUsageOverride;let o=(t.positionalArgs??[]).map(o=>{var a,s,n;let r,i,c,l;return a=e,s=t,i=(r=(n=o).endsWith("?"))?n.slice(0,-1):n,l=(c=/^[a-z-]+(?:\|[a-z-]+)+$/i.test(i))||void 0!==s.usageOverride&&s.usageOverride.startsWith(`${a} ${i}`),r?c?`[${i}]`:l?i:`[${i}]`:l?i:`<${i}>`});return[e,...o].join(" ")}(e,o)}}).map(e=>({label:e.usage,description:e.schema.summary??e.schema.helpDescription}))),d=f("Global Flags:",h(s)),p=g("Agent Quickstart:",r),u=m("Agent Workflows:",n),v=g("Configuration:",i),b=m("Environment:",c),w=g("Examples:",l),`${o}
-${a}
+${b}
 
-${d}
+${o}
 
 ${p}
 
 ${u}
 
-${v}
+${w}
 
-${b}
+${y}
 
-${w}
-`}function h(e){return a().filter(t=>e.has(t.key)&&void 0!==t.usageLabel&&void 0!==t.usageDescription)}function f(e,t){return m(e,t.map(e=>({label:e.usageLabel??"",description:e.usageDescription??""})))}function m(e,t){if(0===t.length)return`${e}
-  (none)`;let o=Math.max(...t.map(e=>e.label.length))+2,a=[e];for(let e of t)a.push(`  ${e.label.padEnd(o)}${e.description}`);return a.join("\n")}function g(e,t){return 0===t.length?`${e}
-  (none)`:[e,...t.map(e=>`  ${e}`)].join("\n")}function v(e){var t,s;let n,r=(n=d[e])?`${n.body}
+${k}
+`}function m(e){return o().filter(t=>e.has(t.key)&&void 0!==t.usageLabel&&void 0!==t.usageDescription)}function f(e,t){return g(e,t.map(e=>({label:e.usageLabel??"",description:e.usageDescription??""})))}function g(e,t){if(0===t.length)return`${e}
+  (none)`;let a=Math.max(...t.map(e=>e.label.length))+2,o=[e];for(let e of t)o.push(`  ${e.label.padEnd(a)}${e.description}`);return o.join("\n")}function v(e,t){return 0===t.length?`${e}
+  (none)`:[e,...t.map(e=>`  ${e}`)].join("\n")}function b(e){var t,s;let n,r=(n=p[e])?`${n.body}
 
 Related:
   agent-device help                  command list and global flags
   agent-device help <command>        command-specific flags
   agent-device help workflow         normal app automation loop
-`:null;if(r)return r;let i=o(e);if(!i)return null;let c=(t=e,(s=i).usageOverride?s.usageOverride:[t,...(s.positionalArgs??[]).map(p),...(s.allowedFlags??[]).flatMap(e=>{var t;return(t=e,a().filter(e=>e.key===t)).map(e=>e.usageLabel??e.names[0])}).map(e=>`[${e}]`)].join(" ")),l=h(new Set(i.allowedFlags??[])),u=[];l.length>0&&u.push(f("Command flags:",l));let m=u.length>0?`
+`:null;if(r)return r;let i=a(e);if(!i)return null;let c=(t=e,(s=i).usageOverride?s.usageOverride:[t,...(s.positionalArgs??[]).map(h),...(s.allowedFlags??[]).flatMap(e=>{var t;return(t=e,o().filter(e=>e.key===t)).map(e=>e.usageLabel??e.names[0])}).map(e=>`[${e}]`)].join(" ")),d=m(new Set(i.allowedFlags??[])),l=[];d.length>0&&l.push(f("Command flags:",d));let u=l.length>0?`
 
-${u.join("\n\n")}`:"";return`agent-device ${c}
+${l.join("\n\n")}`:"";return`agent-device ${c}
 
 ${i.helpDescription}
 
 Usage:
-  agent-device ${c}${m}
-`}export{v as buildCommandUsageText,u as buildUsageText};
+  agent-device ${c}${u}
+`}export{b as buildCommandUsageText,u as buildUsageText};