agent-device 0.13.2 → 0.14.0

package/dist/src/testing/conformance.js

@@ -1 +0,0 @@
-import e from"node:assert/strict";import{commands as a,selector as s}from"../9076.js";let t={session:"default",app:"com.example.app",installSourcePath:"/tmp/example.app",appEventName:"example.ready",appPushPayload:{aps:{alert:"hello"}},visibleSelector:"label=Continue",visibleText:"Continue",editableTarget:s("label=Email"),fillText:"hello@example.com",point:{x:4,y:8},swipeTo:{x:24,y:28}},n=w({name:"capture",cases:[{name:"captures screenshots through the backend primitive",command:"capture.screenshot",run:async(s,t)=>{let n=await a.capture.screenshot(s,{session:t.session});e.equal(typeof n.path,"string"),e.ok(n.path.length>0)}},{name:"captures snapshots with nodes",command:"capture.snapshot",run:async(s,t)=>{let n=await a.capture.snapshot(s,{session:t.session});e.ok(Array.isArray(n.nodes))}}]}),i=w({name:"selectors",cases:[{name:"finds visible text",command:"selectors.find",run:async(s,t)=>{let n=await a.selectors.find(s,{session:t.session,query:t.visibleText,action:"exists"});e.equal(n.kind,"found"),e.equal(n.found,!0)}},{name:"reads text from a selector",command:"selectors.getText",run:async(t,n)=>{let i=await a.selectors.getText(t,{session:n.session,target:s(n.visibleSelector)});e.equal(i.kind,"text"),e.equal(i.text,n.visibleText)}},{name:"checks selector visibility",command:"selectors.isVisible",run:async(t,n)=>{let i=await a.selectors.isVisible(t,{session:n.session,target:s(n.visibleSelector)});e.equal(i.pass,!0)}},{name:"waits for visible text",command:"selectors.waitForText",run:async(s,t)=>{let n=await a.selectors.waitForText(s,{session:t.session,text:t.visibleText,timeoutMs:1});e.equal(n.kind,"text"),e.equal(n.text,t.visibleText)}}]}),o=w({name:"interactions",cases:[{name:"clicks selector targets",command:"interactions.click",run:async(t,n)=>{let i=await a.interactions.click(t,{session:n.session,target:s(n.visibleSelector)});e.equal(i.kind,"selector")}},{name:"presses explicit points",command:"interactions.press",run:async(s,t)=>{let n=await a.interactions.press(s,{session:t.session,target:{kind:"point",...t.point}});e.deepEqual(n.point,t.point)}},{name:"fills editable targets",command:"interactions.fill",run:async(s,t)=>{let n=await a.interactions.fill(s,{session:t.session,target:t.editableTarget,text:t.fillText});e.equal(n.text,t.fillText)}},{name:"types text without a target",command:"interactions.typeText",run:async(s,t)=>{let n=await a.interactions.typeText(s,{session:t.session,text:t.fillText});e.equal(n.text,t.fillText)}},{name:"focuses selector targets",command:"interactions.focus",run:async(t,n)=>{let i=await a.interactions.focus(t,{session:n.session,target:s(n.visibleSelector)});e.equal(i.kind,"selector")}},{name:"long presses selector targets",command:"interactions.longPress",run:async(t,n)=>{let i=await a.interactions.longPress(t,{session:n.session,target:s(n.visibleSelector),durationMs:500});e.equal(i.kind,"selector")}},{name:"swipes explicit points",command:"interactions.swipe",run:async(s,t)=>{let n=await a.interactions.swipe(s,{session:t.session,from:t.point,to:t.swipeTo});e.deepEqual(n.from,t.point)}},{name:"scrolls viewport targets",command:"interactions.scroll",run:async(s,t)=>{let n=await a.interactions.scroll(s,{session:t.session,target:{kind:"viewport"},direction:"down"});e.equal(n.kind,"viewport")}},{name:"pinches through the backend primitive",command:"interactions.pinch",run:async s=>{let t=await a.interactions.pinch(s,{scale:1.1});e.equal(t.kind,"pinch")}}]}),r=w({name:"system",cases:[{name:"presses back",command:"system.back",run:async(s,t)=>{let n=await a.system.back(s,{session:t.session,mode:"in-app"});e.equal(n.kind,"systemBack")}},{name:"presses home",command:"system.home",run:async(s,t)=>{let n=await a.system.home(s,{session:t.session});e.equal(n.kind,"systemHome")}},{name:"rotates devices",command:"system.rotate",run:async(s,t)=>{let n=await a.system.rotate(s,{session:t.session,orientation:"portrait"});e.equal(n.orientation,"portrait")}},{name:"reads keyboard state",command:"system.keyboard",run:async(s,t)=>{let n=await a.system.keyboard(s,{session:t.session,action:"status"});e.equal(n.kind,"keyboardState")}},{name:"reads clipboard text",command:"system.clipboard",run:async(s,t)=>{let n=await a.system.clipboard(s,{session:t.session,action:"read"});e.equal(n.kind,"clipboardText")}},{name:"opens settings",command:"system.settings",run:async(s,t)=>{let n=await a.system.settings(s,{session:t.session});e.equal(n.kind,"settingsOpened")}},{name:"reads alert state",command:"system.alert",run:async(s,t)=>{let n=await a.system.alert(s,{session:t.session,action:"get"});e.equal(n.kind,"alertStatus")}},{name:"opens app switcher",command:"system.appSwitcher",run:async(s,t)=>{let n=await a.system.appSwitcher(s,{session:t.session});e.equal(n.kind,"appSwitcherOpened")}}]}),c=w({name:"apps",cases:[{name:"opens apps by id",command:"apps.open",run:async(s,t)=>{let n=await a.apps.open(s,{session:t.session,app:t.app});e.equal(n.kind,"appOpened"),e.equal(n.target.app,t.app)}},{name:"closes apps by id",command:"apps.close",run:async(s,t)=>{let n=await a.apps.close(s,{session:t.session,app:t.app});e.equal(n.kind,"appClosed"),e.equal(n.app,t.app)}},{name:"lists apps",command:"apps.list",run:async s=>{let t=await a.apps.list(s,{filter:"all"});e.equal(t.kind,"appsList"),e.ok(Array.isArray(t.apps))}},{name:"reads app state",command:"apps.state",run:async(s,t)=>{let n=await a.apps.state(s,{session:t.session,app:t.app});e.equal(n.kind,"appState"),e.equal(n.app,t.app)}},{name:"pushes app payloads",command:"apps.push",run:async(s,t)=>{let n=await a.apps.push(s,{session:t.session,app:t.app,input:{kind:"json",payload:t.appPushPayload}});e.equal(n.kind,"appPushed"),e.equal(n.inputKind,"json")}},{name:"triggers app events",command:"apps.triggerEvent",run:async(s,t)=>{let n=await a.apps.triggerEvent(s,{session:t.session,name:t.appEventName});e.equal(n.kind,"appEventTriggered"),e.equal(n.name,t.appEventName)}}]}),l=w({name:"admin",cases:[{name:"lists devices",command:"admin.devices",run:async s=>{let t=await a.admin.devices(s,{});e.equal(t.kind,"adminDevices"),e.ok(Array.isArray(t.devices))}},{name:"boots devices",command:"admin.boot",run:async s=>{let t=await a.admin.boot(s,{});e.equal(t.kind,"deviceBooted")}},{name:"ensures simulators",command:"admin.ensureSimulator",run:async s=>{let t=await a.admin.ensureSimulator(s,{device:"iPhone 16",runtime:"iOS 18"});e.equal(t.kind,"simulatorEnsured")}},{name:"installs apps from structured sources",command:"admin.install",run:async(s,t)=>{let n=await a.admin.install(s,{app:t.app,source:{kind:"path",path:t.installSourcePath}});e.equal(n.kind,"appInstalled")}},{name:"reinstalls apps from structured sources",command:"admin.reinstall",run:async(s,t)=>{let n=await a.admin.reinstall(s,{app:t.app,source:{kind:"path",path:t.installSourcePath}});e.equal(n.kind,"appReinstalled")}},{name:"installs apps from source resolver",command:"admin.installFromSource",run:async(s,t)=>{let n=await a.admin.installFromSource(s,{source:{kind:"path",path:t.installSourcePath}});e.equal(n.kind,"appInstalledFromSource")}}]}),m=w({name:"recording",cases:[{name:"starts recording",command:"record",run:async s=>{let t=await a.recording.record(s,{action:"start"});e.equal(t.kind,"recordingStarted")}},{name:"stops traces",command:"trace",run:async s=>{let t=await a.recording.trace(s,{action:"stop"});e.equal(t.kind,"traceStopped")}}]}),p=w({name:"diagnostics",cases:[{name:"reads paginated logs",command:"diagnostics.logs",run:async s=>{let t=await a.diagnostics.logs(s,{limit:10});e.equal(t.kind,"diagnosticsLogs"),e.ok(Array.isArray(t.entries))}},{name:"dumps structured network entries",command:"diagnostics.network",run:async s=>{let t=await a.diagnostics.network(s,{limit:10,include:"summary"});e.equal(t.kind,"diagnosticsNetwork"),e.ok(Array.isArray(t.entries))}},{name:"measures perf metrics",command:"diagnostics.perf",run:async s=>{let t=await a.diagnostics.perf(s,{sampleMs:100});e.equal(t.kind,"diagnosticsPerf"),e.ok(Array.isArray(t.metrics))}}]}),d=[n,i,o,r,c,l,m,p];async function u(e,a={}){let s=a.suites??d,t=[];for(let a of s)t.push(await a.run(e));let n=t.flatMap(e=>e.failures);return{target:e.name,passed:t.reduce((e,a)=>e+a.passed,0),failed:t.reduce((e,a)=>e+a.failed,0),failures:n,suites:t}}async function y(e,a={}){let s=await u(e,a);if(s.failed>0)throw AggregateError(s.failures.map(e=>e.error),`${e.name} failed ${s.failed} agent-device conformance case${1===s.failed?"":"s"}`);return s}function w(e){return{name:e.name,cases:e.cases,run:async a=>{let s={...t,...a.fixtures},n=[],i=0;for(let t of e.cases){let o={suite:e.name,caseName:t.name,fixtures:s};try{await a.beforeEach?.(o);let e=await a.createRuntime();await t.run(e,s),i+=1}catch(a){n.push({suite:e.name,caseName:t.name,command:t.command,error:a})}finally{await a.afterEach?.(o)}}return{suite:e.name,passed:i,failed:n.length,failures:n}}}}export{l as adminConformanceSuite,c as appsConformanceSuite,y as assertCommandConformance,n as captureConformanceSuite,d as commandConformanceSuites,t as defaultCommandConformanceFixtures,p as diagnosticsConformanceSuite,o as interactionConformanceSuite,m as recordingConformanceSuite,u as runCommandConformance,i as selectorConformanceSuite,r as systemConformanceSuite};

package/dist/src/update-check-entry.js

@@ -1 +0,0 @@
-import{readUpdateCheckWorkerArgs as e,runUpdateCheckWorker as c}from"./113.js";let o=e(process.argv.slice(2));o&&c(o).catch(()=>{process.exitCode=0});

package/skills/agent-device/references/bootstrap-install.md

@@ -1,244 +0,0 @@
-# Bootstrap and Install
-
-## When to open this file
-
-Open this file when you still need to choose the right target, start the right session, install or relaunch the app, or pin automation to one device before interacting. This is the deterministic setup layer for sandbox, cloud, or other environments where install paths, device state, or app readiness may be uncertain.
-
-## Open-first path
-
-- `devices`
-- `apps`
-- `ensure-simulator`
-- `open`
-- `session list`
-
-Use this exact order when you are not sure about the installed app identifier. On Android dev builds in particular, `apps` is cheaper than guessing package suffixes and retrying failed `open` calls.
-
-## Install path
-
-- `install` or `reinstall`
-- `install-from-source` when the artifact already exists at a URL the daemon can reach
-- `install-from-source --github-actions-artifact` when a compatible remote daemon should resolve a GitHub Actions artifact
-
-## Most common mistake to avoid
-
-Do not start acting before you have pinned the correct target and opened an `app` session. In mixed-device environments, always pass `--device`, `--udid`, or `--serial`.
-
-## Deterministic setup rule
-
-If there is no simulator, no app install, no open app session, or any uncertainty about where the app should come from, stay in this file and use deterministic setup commands or bootstrap scripts first. Do not improvise install paths or app-launch flows while exploring.
-
-After setup is confirmed or completed, move to `exploration.md` before doing UI inspection or interaction.
-
-## Open-first rule
-
-- If the user asks to test an app and does not provide an install artifact or explicit install instruction, try `open <app>` first.
-- If `open <app>` fails, run `agent-device apps` and retry with a discovered app name before considering install steps.
-- Do not install or reinstall on the first attempt unless the user explicitly asks for installation or provides a concrete artifact path or URL.
-- When installation is required from a known location, prefer a checked-in shell script or other deterministic bootstrap command over ad hoc path guessing.
-- Use `apps --platform <platform>` together with `--device`, `--udid`, or `--serial` when target selection matters.
-- Once you have the correct app name, retry `open` with that exact discovered value.
-
-## Common starting points
-
-These are examples, not required exact sequences. Use the smallest setup flow that matches the task.
-
-### Boot a simulator and open an app
-
-```bash
-agent-device ensure-simulator --platform ios --device "iPhone 17 Pro" --boot
-agent-device open MyApp --platform ios --device "iPhone 17 Pro" --relaunch
-```
-
-### Install an app artifact
-
-```bash
-agent-device install com.example.app ./build/app.apk --platform android --serial emulator-5554
-```
-
-```bash
-agent-device install com.example.app ./build/MyApp.app --platform ios --device "iPhone 17 Pro"
-```
-
-```bash
-ARTIFACT_URL="<trusted-artifact-url>"
-agent-device install-from-source "$ARTIFACT_URL" --platform android
-```
-
-Daemon-resolved GitHub Actions artifacts:
-
-```bash
-agent-device install-from-source \
-  --github-actions-artifact ORG/REPO:1234567890 \
-  --platform android
-```
-
-Project config can provide an artifact name instead:
-
-```json
-{
-  "platform": "android",
-  "installSource": {
-    "type": "github-actions-artifact",
-    "repo": "ORG/REPO",
-    "artifact": "app-debug"
-  }
-}
-```
-
-## Install guidance
-
-- Use `install <app> <path>` when the app may already be installed and you do not need a fresh-state reset.
-- Use `reinstall <app> <path>` when you explicitly need uninstall plus install as one deterministic step.
-- Use `install-from-source <url>` only when an existing artifact URL is trusted, operator-approved, and reachable by the daemon.
-- Use `--github-actions-artifact <org>/<repo>:<artifact>` when a compatible remote daemon should resolve a GitHub Actions artifact. Numeric artifacts are IDs; non-numeric artifacts are names.
-- Local `.apk`, `.aab`, `.app`, and `.ipa` paths go through `install` or `reinstall`; existing reachable URLs go through `install-from-source`.
-- Do not download, re-zip, publish temporary GitHub releases, or move CI artifacts elsewhere just to make an install command work.
-- Keep install and open as separate phases. Do not turn them into one default command flow.
-- Supported binary formats:
-  - Android: `.apk` and `.aab`
-  - iOS: `.app` and `.ipa`
-- Android URL sources can be direct `.apk` or `.aab` files.
-- Trusted artifact service URLs may point at archive-backed downloads that contain one installable artifact. Prefer `--github-actions-artifact` for GitHub Actions artifacts that a compatible remote daemon can resolve with its own credentials.
-- If a trusted artifact archive contains multiple installables, stop and ask for the intended artifact instead of guessing.
-- `.aab` still requires `bundletool` in `PATH`, or `AGENT_DEVICE_BUNDLETOOL_JAR=<absolute-path-to-bundletool-all.jar>` with `java` in `PATH`, when the daemon installs the materialized artifact.
-- For `.ipa` archives with multiple app bundles, `<app>` is the bundle id or bundle name selection hint.
-- After install or reinstall, later use `open <app>` with the exact discovered or known package/bundle identifier, not the artifact path.
-
-## Choose the right starting point
-
-- iOS local QA: prefer simulators unless the task explicitly requires physical hardware.
-- iOS in mixed simulator and device environments: run `ensure-simulator` first, then keep using `--device` or `--udid`.
-- TV targets: use `--target tv` together with `--platform` when the task is for tvOS or Android TV rather than phone or tablet surfaces.
-- Android binary flow: use `install` or `reinstall` for `.apk` or `.aab`, then open by installed package name.
-- macOS desktop app flow: use `open <app> --platform macos`. Only load [macos-desktop.md](macos-desktop.md) if a desktop surface or macOS-specific behavior matters.
-
-TV example:
-
-```bash
-agent-device open MyTvApp --platform ios --target tv
-agent-device open com.example.androidtv --platform android --target tv
-```
-
-## Session rules
-
-- Use `--session <name>` when you need a named session:
-
-```bash
-agent-device --session auth open Settings --platform ios
-agent-device --session auth snapshot -i
-```
-
-- Use `open <app>` before interactions.
-- Use `close` when done. Add `--shutdown` when you want simulators or emulators torn down with the session.
-- Use semantic session names when you need multiple concurrent runs.
-- Use `--save-script=<path>` on `close` when you want to keep a replay script.
-- For dev loops where state can linger, prefer `open <app> --relaunch`.
-- For Metro-backed React Native JS changes with the app already running, prefer `metro reload` instead of `open <app> --relaunch`; it asks Metro to reload connected apps without restarting the native process.
-- In iOS sessions, use `open <app>` for the app itself. Use `open <url>` for deep links, and `open <app> <url>` when you need to launch the app and deep link in one step.
-- On iOS, `appstate` is session-scoped and requires the matching active session on the target device.
-
-## After a session is established
-
-Once you have opened the correct session on the correct target, default to the conservative rule: keep the session binding on follow-up commands, and stop repeating device-routing flags unless you are intentionally retargeting.
-
-- Prefer `--session <name>` on follow-up commands, or use sandboxed `AGENT_DEVICE_SESSION`.
-- Do not keep repeating `--platform`, `--target`, `--device`, `--udid`, `--serial`, or similar target-selection flags on normal follow-up commands.
-- Only omit follow-up session flags when the environment explicitly guarantees isolation.
-
-Good shared-host pattern:
-
-```bash
-agent-device --session auth open Settings --platform ios --device "iPhone 17 Pro"
-agent-device --session auth snapshot -i
-agent-device --session auth press @e3
-agent-device --session auth close
-```
-
-Bad shared-host pattern:
-
-```bash
-agent-device --session auth open Settings --platform ios --device "iPhone 17 Pro"
-agent-device --session auth snapshot -i --platform ios --device "iPhone 17 Pro"
-```
-
-Use target-selection flags again only when you are choosing the target before opening a session, or when you explicitly mean to retarget.
-
-## Session-bound automation
-
-Use this when an orchestrator must keep plain CLI calls on one session and device.
-
-```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_SESSION` plus `AGENT_DEVICE_PLATFORM` provides the default binding.
-- `--session-lock reject|strip` controls whether conflicting per-call routing flags fail or are ignored.
-- Conflicts include explicit retargeting flags such as `--platform`, `--target`, `--device`, `--udid`, `--serial`, `--ios-simulator-device-set`, and `--android-device-allowlist`.
-- Lock policy applies to nested `batch` steps too.
-- Compatibility aliases remain supported: `--session-locked`, `--session-lock-conflicts`, `AGENT_DEVICE_SESSION_LOCKED`, and `AGENT_DEVICE_SESSION_LOCK_CONFLICTS`.
-
-Android emulator variant:
-
-```bash
-export AGENT_DEVICE_SESSION=qa-android
-export AGENT_DEVICE_PLATFORM=android
-
-agent-device --session-lock reject open com.example.myapp --relaunch
-```
-
-## Scoped discovery
-
-Use scoped discovery when one run 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 `--device`, `--udid`, and `--serial`.
-- Out-of-scope selectors fail with `DEVICE_NOT_FOUND`.
-- With iOS simulator-set scope enabled, iOS physical devices are not enumerated.
-- If the scoped iOS simulator set is empty, the error should point at the set path and suggest creating a simulator in that set.
-- Environment equivalents:
-  - `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET`
-  - `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST`
-
-## Session inspection and replay
-
-```bash
-agent-device session list
-agent-device replay ./session.ad --session auth
-agent-device replay -u ./session.ad --session auth
-```
-
-- iOS session entries include `device_udid` and `ios_simulator_device_set`. Use them to confirm routing in concurrent runs.
-- Prefer selector-based actions and assertions in saved replay scripts.
-- Tenant isolation namespaces sessions as `<tenant>:<session>` during tenant-scoped runs.
-
-## When to leave this file
-
-- Once the correct target and session are pinned, move to [exploration.md](exploration.md).
-- If opening, startup, permissions, or logs become the blocker, switch to [debugging.md](debugging.md).
-
-## Install examples
-
-```bash
-agent-device reinstall MyApp /path/to/app-debug.apk --platform android --serial emulator-5554
-```
-
-```bash
-agent-device install com.example.app ./build/MyApp.ipa --platform ios --device "iPhone 17 Pro"
-```
-
-Do not use `open <apk|aab> --relaunch` on Android.
-
-## Security and trust notes
-
-- Treat signing, provisioning, and daemon auth values as host secrets. Do not paste them into shared logs or commit them to source control.
-- Prefer Xcode Automatic Signing over manual overrides when a physical iOS device is involved.
-- Keep persistent host-specific defaults in environment variables rather than checked-in project config.

package/skills/agent-device/references/coordinate-system.md

@@ -1,28 +0,0 @@
-# Coordinate System
-
-## When to open this file
-
-Open this file only when you must use raw coordinates instead of selectors or `@ref` targeting.
-
-## Main commands to reach for first
-
-- `screenshot`
-- coordinate-based `click` or `swipe`
-
-## Most common mistake to avoid
-
-Do not assume coordinates mean the same thing across platforms or runs. Prefer selectors and refs first.
-
-## Canonical loop
-
-```bash
-agent-device screenshot /tmp/current-screen.png
-agent-device click 120 240
-```
-
-## Rules
-
-- Origin is the top-left of the device screen.
-- iOS uses device points.
-- Android uses pixels.
-- Use screenshots to reason about coordinates before acting.

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

@@ -1,138 +0,0 @@
-# Debugging
-
-## When to open this file
-
-Open this file when the task turns into failure triage, logs, network inspection, permission prompts, setup trouble, or unstable session behavior.
-
-If the debugging task needs the React Native component tree, props, state, hooks, or render profiling, use `agent-device react-devtools ...` and the `skills/react-devtools` workflow instead of trying to infer those internals from the accessibility tree or app logs alone.
-
-## Main commands to reach for first
-
-- `logs clear --restart`
-- `network dump`
-- `logs path`
-- `logs doctor`
-- `alert wait`
-- `alert accept` or `alert dismiss`
-
-## Most common mistake to avoid
-
-Do not leave logging on for normal flows or dump full log files into context. Keep debug windows short and inspect logs with `grep` or `tail`.
-
-In React Native dev or debug builds, do not dismiss visible warning or error overlays without remembering to report them later. If you close one to keep the flow moving, keep at least a screenshot or a short marked log window so the summary can name it.
-
-## Canonical loop
-
-```bash
-agent-device open MyApp --platform ios
-agent-device logs clear --restart
-agent-device network dump 25
-agent-device logs path
-agent-device close
-```
-
-## Log and network flow
-
-Logging is off by default. Enable it only when you need a debugging window.
-
-- Default app logs live under `~/.agent-device/sessions/<session>/app.log`.
-- `logs clear --restart` is the fastest clean repro loop.
-- `network dump [limit] [summary|headers|body|all]` parses recent HTTP(s) entries from the same session app log.
-- On macOS, `network dump` is app-scoped and only sees Unified Logging associated with the active session app.
-- On iOS simulators, `network dump` can recover recent app log history with `simctl log show` when the live session stream is sparse, so check the returned notes before assuming the repro window was empty.
-- On iOS, `network dump` is still limited to what Unified Logging exposes for the app process. If the app does not emit request metadata there, `network dump` can legitimately return no HTTP entries even during a real repro.
-- Summary output already shows timestamp, status, and duration when the log backend exposes them.
-- Prefer the explicit flag form `network dump 25 --include headers|body|all` when you need more than the default summary view.
-- If iOS simulator notes say app logs were recovered but none looked like HTTP traffic, treat that as an app instrumentation gap rather than a missing repro and inspect `logs path` for the non-network diagnostics that were captured.
-- `logs doctor` checks backend and runtime readiness for the current session and device.
-- `logs mark "before tap"` inserts a timestamped marker into the app log.
-- Android `network dump` surfaces timestamps from logcat-style prefixes and can backfill status and request/response duration from adjacent GIBSDK packet lines, so check it before dumping raw log windows.
-- Android app-log streaming rebinds to the current app PID after relaunches, so rerun the repro window before assuming the last log slice is stale.
-- Marker lines are emitted with the `[agent-device][mark][...]` prefix. When you grep later, prefer a narrow pattern such as `grep -n -E "agent-device.*mark|before tap" <path>`.
-- Session app logs can contain runtime data, headers, or payload fragments. Review them before sharing.
-- `logs start` requires an active app session and appends to `app.log`.
-- `logs stop` stops streaming. `close` also stops logging.
-- `logs clear` truncates `app.log` and removes rotated `app.log.N` files, and requires logging to be stopped first.
-- `logs path` returns the log path plus metadata about the active backend and file state.
-- `network log` is an alias for `network dump`.
-
-Operational limits:
-
-- `app.log` rotates to `app.log.1` after 5 MB by default.
-- `network dump` scans the last 4000 app-log lines, returns up to 200 entries, and truncates header or payload fields at 2048 characters.
-- Retention knobs:
-  - `AGENT_DEVICE_APP_LOG_MAX_BYTES`
-  - `AGENT_DEVICE_APP_LOG_MAX_FILES`
-- Redaction hook:
-  - `AGENT_DEVICE_APP_LOG_REDACT_PATTERNS`
-
-Useful shell follow-up after `logs path`:
-
-```bash
-grep -n -E "Error|Exception|Fatal|crash" <path>
-grep -n -E "agent-device.*mark|before tap" <path>
-tail -50 <path>
-```
-
-If the app showed a visible warning or error overlay during the flow:
-
-- Prefer a narrow grep window around your `logs mark` lines instead of loading the whole file.
-- Mention the surfaced warning or error in the final summary even if it did not block completion.
-- If the overlay kept returning, call that out as a stability issue instead of treating it as operator noise.
-
-## Alerts and permissions
-
-Use `alert` for iOS simulator permission dialogs and macOS desktop alerts instead of tapping coordinates.
-
-```bash
-agent-device alert wait 5000
-agent-device alert accept
-```
-
-- `alert` is supported on iOS simulators and macOS desktop targets.
-- `alert accept` and `alert dismiss` retry internally for a short window, so you usually do not need manual sleeps.
-- If a permission sheet or modal is visible in `snapshot` or `screenshot` but `alert accept` says no alert was found, treat it as normal tappable UI for that run: take a scoped `snapshot -i -s "<visible label>"` and `press @ref` instead of looping on `alert`.
-- iOS 16+ "Allow Paste" prompts are suppressed under XCUITest. Use `xcrun simctl pbcopy booted` when you need to seed simulator clipboard content directly.
-
-## Setup problems worth recognizing early
-
-- iOS snapshots do not require macOS Accessibility permissions.
-- iOS physical-device XCTest setup does require valid signing and provisioning.
-- If physical-device runner setup fails, prefer Xcode Automatic Signing first.
-- Optional overrides are:
-  - `AGENT_DEVICE_IOS_TEAM_ID`
-  - `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
-  - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
-  - `AGENT_DEVICE_IOS_BUNDLE_ID`
-- If daemon startup is timing out during setup, increase `AGENT_DEVICE_DAEMON_TIMEOUT_MS`.
-- If daemon startup fails with stale metadata hints, clean `~/.agent-device/daemon.json` and `~/.agent-device/daemon.lock`, then retry.
-- Free Apple Developer personal-team accounts may reject generic bundle IDs. Use a unique reverse-DNS value for `AGENT_DEVICE_IOS_BUNDLE_ID` when that happens.
-
-## Common failure patterns
-
-- `snapshot` returns 0 nodes: the app may no longer be foregrounded or the UI is not stable yet. Re-open the app or retry when state settles.
-- Logs are empty: confirm you opened an app session before `logs clear --restart`.
-- Android logs look stale after relaunch: retry the repro window after the process rebinds.
-- Android accessibility snapshots can lag behind visible screen transitions. The next snapshot retries suspicious trees for a short post-action deadline after navigation-sensitive actions, and `@ref` actions refresh while that window is active. If the tree still looks stale, use `screenshot` as visual truth, wait briefly, then re-run `snapshot -i`. For animation-heavy runs, try `settings animations off` and restore with `settings animations on`.
-- React Native dev warnings or errors keep reappearing: treat them as part of the app state, not as disposable chrome. Capture one clean repro and include them in the summary.
-- Permission prompts block the flow: wait for the alert and handle it explicitly.
-- If snapshots keep returning 0 nodes on an iOS simulator, restart Simulator and re-open the app.
-- If a macOS snapshot looks incomplete, compare with `snapshot --raw --platform macos` to separate collector filtering from missing AX content.
-
-## 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>
-```
-
-- iOS: if the log suggests `ReportCrash`, `SIGABRT`, or `EXC_*`, inspect `~/Library/Logs/DiagnosticReports`.
-- Android: if the app log is not enough, use `adb logcat` for `FATAL EXCEPTION`, `Abort message`, or `signal` lines around process death.
-- If no crash signature appears in app logs, stop collecting broad logs and switch to the platform-native crash source.
-
-## When to leave this file
-
-- Return to [exploration.md](exploration.md) once the app is stable again.
-- Load [verification.md](verification.md) if you need evidence artifacts after reproducing the issue.