adb-ready 0.5.1 → 0.7.0

package/docs/target-pools.md

@@ -0,0 +1,151 @@
+# Target pools and fan-out
+
+Use a target pool when the same bounded verification must run against an
+explicit set of Android targets. Pool mode is opt-in. A normal `adb-ready run`
+still selects exactly one target.
+
+Every acquired member receives its own single-target session, target lease,
+verifier result, cleanup, and evidence bundle. The pool result aggregates those
+unchanged member envelopes in declaration order.
+
+## Declare a local pool
+
+```json
+{
+  "$schema": "./node_modules/adb-ready/schema/config-v1.schema.json",
+  "version": 1,
+  "targets": {
+    "pools": {
+      "smoke": {
+        "maxConcurrency": 2,
+        "failFast": false,
+        "leaseWaitMs": 30000,
+        "members": [
+          { "id": "desk", "kind": "adb", "serial": "R3CT..." },
+          { "id": "api36", "kind": "avd", "name": "Pixel_9_API_36" },
+          {
+            "id": "lab",
+            "kind": "remote-adb",
+            "host": "android-lab.internal",
+            "port": 5037,
+            "serial": "10.20.0.15:5555"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Run the same verifier on every member:
+
+```bash
+adb-ready run --pool smoke -- npm run test:e2e
+```
+
+Preview every member without inspecting ADB, starting an AVD, or running the
+verifier:
+
+```bash
+adb-ready run --pool smoke --dry-run --json -- npm run test:e2e
+```
+
+The pool owns concurrency policy; it never infers an unbounded worker count.
+Override it for one invocation only when the CI runner has known capacity:
+
+```bash
+adb-ready run --pool smoke --max-concurrency 1 --fail-fast \
+  --lease-wait 45s -- npm run test:e2e
+```
+
+## Member kinds
+
+| Kind | Required fields | Ownership |
+| --- | --- | --- |
+| `adb` | `id`, exact `serial` | Uses an already ADB-visible target. |
+| `avd` | `id`, exact existing AVD `name` | Reuses or starts that AVD; stops only an emulator process started by this run. |
+| `remote-adb` | `id`, `host`, exact `serial`; optional `port` | Uses the explicit ADB server without changing the global local server. |
+| `firebase` | `id`, `model`, `version`; optional `locale`, `orientation` | Firebase owns the remote target and lifecycle. Use only with `test firebase`. |
+
+Member IDs and resource identities must be unique inside a pool. Members are
+required by default. Set `"required": false` only when that dimension is truly
+informational; an optional failure remains visible but does not fail the
+aggregate.
+
+## Firebase dimensions
+
+A Firebase-only pool submits one independently observable matrix per declared
+dimension. This gives every dimension a stable member result and lets ADB Ready
+bound submission concurrency.
+
+```json
+{
+  "version": 1,
+  "targets": {
+    "pools": {
+      "firebase-smoke": {
+        "maxConcurrency": 2,
+        "failFast": true,
+        "members": [
+          { "id": "pixel-api35", "kind": "firebase", "model": "akita", "version": "35" },
+          { "id": "tablet-api34", "kind": "firebase", "model": "tangorpro", "version": "34" }
+        ]
+      }
+    }
+  }
+}
+```
+
+```bash
+adb-ready test firebase instrumentation \
+  --pool firebase-smoke \
+  --project my-project \
+  --app app-debug.apk \
+  --test-apk app-debug-androidTest.apk
+```
+
+Dimensions are checked against the live Firebase catalog before upload. With
+`failFast`, ADB Ready stops submitting queued dimensions after a required
+failure. It does not cancel matrices already running remotely. Use
+`adb-ready test firebase cancel` for an intentional provider cancellation.
+
+## Queueing and leases
+
+ADB Ready serializes contending work with an owner-recorded, heartbeating lease.
+`leaseWaitMs` bounds how long a pool member waits; cancellation exits the queue
+without taking ownership. Expired leases and leases owned by a dead process on
+the same host are recovered conservatively.
+
+The built-in coordination backend is a per-user filesystem on one host. It is
+not a distributed lock. CI jobs on different machines need runner-level
+routing or another explicit external coordination system. ADB Ready never
+infers cross-host ownership.
+
+An explicit remote ADB server is also a trust boundary: its socket is not
+encrypted by ADB Ready. Protect it with a trusted private network, VPN, SSH
+tunnel, or equivalent transport; never expose port 5037 to an untrusted
+network.
+
+## Aggregate result
+
+Human output shows the status of every member. JSON and NDJSON preserve every
+nested result envelope, including its command ID, structured problems,
+timestamps, and evidence path. The aggregate cannot report success when any
+required member failed, disappeared, was cancelled, or never started.
+
+Useful automation fields:
+
+```text
+data.pool
+data.maxConcurrency
+data.failFast
+data.coordination
+data.members[].id
+data.members[].status
+data.members[].exitCode
+data.members[].result
+data.summary
+```
+
+Pool configuration is declarative data. It cannot add executable hooks or
+shell fragments, and every verifier continues to use direct argv execution.

package/docs/targets-and-wireless.md

@@ -96,6 +96,21 @@ This is useful for WSL, containers, VMs, SSH-forwarded workstations, and device
 labs. ADB Ready does not start, kill, or reconfigure that shared server
 implicitly.
 
+Before every command sent through an explicit `--adb-host` or `--adb-port`, ADB
+Ready opens a bounded read-only connection and requests only `host:version`.
+The real `adb` process starts only when the server protocol matches the local
+client. This matters because the upstream ADB client automatically sends
+`host:kill` when it encounters a mismatched server version (see the
+[AOSP ADB client implementation](https://android.googlesource.com/platform/packages/modules/adb/+/refs/heads/main/client/adb_client.cpp)).
+ADB Ready instead returns `ADB_REMOTE_SERVER_PROTOCOL_MISMATCH` and leaves the
+shared server untouched.
+
+The preflight also distinguishes an unreachable route, timeout, cancellation,
+and a non-ADB response. It is repeated before each command so replacement of a
+server during a long session fails closed. This is a narrow safety handshake,
+not a replacement ADB transport; all device operations still use the selected
+`adb` executable.
+
 ## Network limitations
 
 Wireless discovery and connection can be blocked by guest Wi-Fi, client
@@ -110,6 +125,12 @@ adb-ready doctor --verbose
 adb-ready devices
 ```
 
+For WSL, a container, VM, or remote runner, first verify that its network
+namespace can reach the exact protected ADB host and port. A successful DNS
+lookup or mDNS discovery does not prove that the TCP route is usable. ADB Ready
+reports this as `ADB_REMOTE_SERVER_UNREACHABLE` rather than an empty target
+list.
+
 If discovery is unavailable but the device shows a reachable connection
 endpoint, pass it explicitly. Do not assume port `5555`; modern Wireless
 debugging ports are dynamic.

package/docs/threat-model.md

@@ -39,6 +39,12 @@ selection fails. An MCP connection binds one target and refuses a silent
 switch. UI references include the current hierarchy digest and are revalidated
 immediately before mutation.
 
+MCP profiles narrow discovery for a workflow and reduce accidental tool
+selection, but they are not an authorization boundary. Every exposed operation
+still applies its own target, path, input, ownership, and destructive-action
+checks. Tool annotations and namespaced sensitivity metadata help clients choose
+approval policy; they are hints, not security enforcement.
+
 ### Unsafe file mutation
 
 Capture and setup paths are constrained to the project, checked for unsafe
@@ -52,6 +58,20 @@ redacted. Pairing codes use protected input or stdin and never enter process
 arguments. Screenshots and UI hierarchies require explicit calls and never join
 AI context automatically.
 
+Screenshot capture rejects malformed PNG structure, invalid checksums,
+unsupported encodings, and excessive source dimensions before publishing a
+file. MCP image results are cropped or proportionally bounded by default and
+must fit an encoded payload budget; full-resolution delivery is an explicit
+client choice. These controls bound transport and context size, not the visual
+sensitivity of the selected pixels.
+
+Failure inspection accepts only a verified installed package, binds every
+probe to the same target, uses package-scoped exit history and log filtering,
+and retains DropBox blocks only when an exact package or package-process line
+matches. Unavailable or permission-limited sources are reported rather than
+replaced by target-wide evidence. Source bytes, time windows, record counts,
+and returned excerpts are bounded and redacted.
+
 ### Unbounded or misleading automation
 
 Process output, recordings, UI trees, session storage, context, retries, and
@@ -59,6 +79,12 @@ waits are bounded. Results distinguish process acceptance (`ok`) from observed
 postconditions (`verified`). An unchanged UI is reported as a verification gap,
 not silently upgraded to verified success.
 
+Keyboard dismissal requires two independent Android visibility signals to
+agree before Back is sent and after it completes. Runtime-permission responses
+require one recognized PermissionController dialog and one exact resource ID;
+localized labels, generic system dialogs, biometric prompts, notification
+setup, and ambiguous OEM states are never accepted speculatively.
+
 ### Network exposure
 
 The 0.2 MCP server uses stdio and opens no listener. ADB itself may connect to a
@@ -73,6 +99,13 @@ ADB Ready's isolation boundary.
 - autonomous destructive recovery;
 - automatic screenshot or UI-text upload.
 
+Protected UI text is accepted from CLI stdin or by environment-variable name
+through MCP. It is not placed in host argv, result envelopes, plans, journals,
+screenshots created by the action, or AI context. It still exists transiently
+in ADB Ready memory and the child-process pipe, and the selected Android target,
+input method, app, or OEM auditing may observe it. ADB Ready does not claim to
+turn a normal visible field or an untrusted target into a secure channel.
+
 ## Residual risk
 
 A trusted ADB server can control connected Android targets, and an approved AI

package/docs/troubleshooting.md

@@ -21,6 +21,9 @@ adb-ready context --since 5m --only problems,recovery,logs
 | `ADB_NOT_FOUND` | No usable ADB executable was resolved | Install Platform-Tools or pass `--adb PATH` |
 | `ADB_SERVER_UNAVAILABLE` | The selected local or remote server could not be queried | Check the configured host/port and run `adb start-server` explicitly if appropriate |
 | `ADB_VERSION_MISMATCH` | Client and server report incompatible versions | Align Platform-Tools versions; review before restarting the shared server |
+| `ADB_REMOTE_SERVER_UNREACHABLE` | The explicit server socket has no usable route | Check WSL/container/VM/VPN/firewall/tunnel routing; do not expose port 5037 publicly |
+| `ADB_REMOTE_SERVER_PROTOCOL_MISMATCH` | Remote and local ADB protocols differ | Align Platform-Tools deliberately; ADB Ready will not let upstream ADB kill the shared server |
+| `ADB_REMOTE_SERVER_INVALID_RESPONSE` | The endpoint or local client could not complete the read-only protocol preflight | Verify the host, port, tunnel destination, and local Platform-Tools installation |
 | `TARGET_UNAUTHORIZED` | Android has not authorized this host | Unlock the device and accept its RSA debugging prompt |
 | `TARGET_NO_PERMISSIONS` | The host cannot access the USB device | Fix host USB permissions or rules, then reconnect |
 | `TARGET_OFFLINE` | ADB knows the transport but it is not ready | Check cable/network state and retry `devices` |
@@ -34,6 +37,11 @@ adb-ready context --since 5m --only problems,recovery,logs
 | `UI_HIERARCHY_BUSY` | Another process held the selected target's single UI Automation service through the UI timeout | Let that capture finish or increase the UI timeout, then retry |
 | `UI_HIERARCHY_LOCK_UNAVAILABLE` | The per-user coordination directory is not writable | Restore write access to the ADB Ready state directory, then retry |
 | `UI_NOT_IDLE` | Android UI Automator could not observe a quiet accessibility window | Pause continuous UI changes or navigate to a stable screen, then retry |
+| `UI_UNICODE_INPUT_UNAVAILABLE` | Unicode/multiline input was requested but ADBKeyBoard is not installed and enabled | Install a compatible official ADBKeyBoard release, enable it in Android settings, and retry; ADB Ready will not enable an IME silently |
+| `UI_INPUT_METHOD_UNKNOWN` | Android did not expose the current IME, so it cannot be restored safely | Select a keyboard on the target before retrying Unicode input |
+| `UI_KEYBOARD_STATE_AMBIGUOUS` | InputMethodManager and WindowInsets disagree about keyboard visibility | Wait for the transition to settle, then inspect again; ADB Ready will not press Back while state is uncertain |
+| `UI_KEYBOARD_STATE_UNSUPPORTED` | The Android build omitted one of the two required keyboard signals | Dismiss the keyboard in the app or use a target that exposes both dumpsys states |
+| `UI_PERMISSION_DIALOG_UNSUPPORTED` | The current PermissionController or OEM dialog is not one exact supported runtime-permission prompt | Handle the dialog manually; notification, biometric, Settings, and unknown OEM dialogs are not auto-accepted |
 | `SESSION_RECOVERY_FAILED` | The bounded target/port recovery budget was exhausted | Inspect `problems`, network state, and saved recovery events |
 | `SESSION_PERSISTENCE_FAILED` | The private session record could not be written | Check user-state directory permissions and capacity |
 | `FRAMEWORK_LAUNCHER_NOT_FOUND` | The detected Flutter or Gradle project has no runnable launcher | Install Flutter and expose `flutter` on PATH, or restore the project's checked-in Gradle Wrapper |
@@ -135,6 +143,37 @@ Resolve the user-action problem, then start a new session. Increase the recovery
 budget only when the environment is known to need more time; do not use an
 unbounded timeout.
 
+## Screenshot capture is rejected
+
+`SCREENSHOT_BOUNDS_INVALID` means the requested `--crop X,Y,WIDTH,HEIGHT` lies
+outside the decoded source image. Capture once without a crop and read the
+reported `image.source` dimensions, then retry with coordinates inside them.
+
+`SCREENSHOT_PAYLOAD_TOO_LARGE` protects an MCP client from an unexpectedly
+large image. Crop the relevant region or lower `maxWidth`/`maxHeight`; use
+`fullResolution: true` only when the client can deliberately accept it.
+
+`SCREENSHOT_INVALID` or `SCREENSHOT_ENCODING_UNSUPPORTED` means ADB did not
+produce a complete standard non-interlaced 8-bit PNG. Confirm that the selected
+display is available and not blocked by a secure surface, then retry without
+assuming that a PNG signature alone proves usable evidence.
+
+## Failure inspection has unavailable sources
+
+`adb-ready inspect failures APP_ID` succeeds when the app and target are
+verified even if an optional Android evidence source is absent. Read the
+`sources` list: each entry distinguishes available, truncated,
+permission-limited, and unsupported evidence.
+The top-level `truncated` flag means the requested incident limit bounded the
+combined result; a source-level flag means Android output or log retention was
+bounded before correlation.
+
+Application exit history requires Android 11/API 30 or a compatible OEM
+backport. DropBox visibility varies by Android build and shell permissions.
+ADB Ready does not substitute unrelated target-wide crashes. Use a recent
+`--since` window, reproduce the failure, and retry; use focused `adb-ready logs`
+when the app is still running and live output is required.
+
 ## Report a reproducible issue
 
 For ordinary bugs, open a GitHub issue with the ADB Ready version, host/runtime,

package/docs/ui-automation.md

@@ -30,6 +30,33 @@ parallel, and selector processing or input does not hold the capture lock. If
 another process does not finish within the configured UI timeout, the command
 returns `UI_HIERARCHY_BUSY` instead of misreporting an inaccessible screen.
 
+Choose an acquisition profile when the default one-shot observation is not the
+right tradeoff:
+
+```bash
+adb-ready inspect ui --acquisition balanced
+adb-ready inspect ui --acquisition fast --interactive-only
+adb-ready inspect ui --acquisition strict
+```
+
+- `balanced` takes one fresh platform-idle snapshot within the normal bounded
+  UI timeout and is the default.
+- `fast` keeps the same safe target-scoped platform backend but limits the
+  attempt to three seconds. It reports a timeout or non-idle screen instead of
+  pretending that an empty result is a valid screen.
+- `strict` requires two consecutive matching hierarchy digests within at most
+  three captures. A continuously changing screen returns
+  `UI_HIERARCHY_UNSTABLE`.
+
+Every successful structured snapshot reports its observation time, duration,
+attempt count, stability status, source and idle strategy, requested filters,
+node limits, truncation, observed display bounds and rotation, and detected
+semantic limitations. An empty hierarchy is an explicit `UI_HIERARCHY_EMPTY`
+failure. WebView, Compose, and Flutter
+markers are reported only when their corresponding platform view is actually
+observed; they describe framework accessibility boundaries rather than guessing
+why an otherwise unreadable window failed.
+
 ## Audit one screen for people and agents
 
 ```bash
@@ -92,6 +119,7 @@ field happens to be focused:
 adb-ready ui get 'id=com.example:id/email' --json
 adb-ready ui fill 'id=com.example:id/email' 'person@example.com'
 adb-ready ui fill 'id=com.example:id/search' 'pixel' --submit
+adb-ready ui fill 'id=com.example:id/name' 'Příliš žluťoučký 🦊' --input-mode unicode
 adb-ready ui clear 'id=com.example:id/search'
 ```
 
@@ -128,9 +156,84 @@ node whose `scrollable` property is true; without a selector it uses the screen.
 Supported keys are `back`, `home`, `enter`, `menu`, `volume-up`, and
 `volume-down`.
 
-Android's text-input command passes through a device shell. ADB Ready therefore
-accepts only 1–256 ASCII letters, numbers, spaces, and `._@+,:/-`. Unsupported
-characters are rejected instead of being reinterpreted by a shell.
+Text input is bounded to 1–256 Unicode code points and 4096 UTF-8 bytes. The
+default `--input-mode auto` uses Android's built-in `input text` only for the
+conservative ASCII set of letters, numbers, spaces, and `._@+,:/-`. Use
+`--input-mode ascii` to require that path explicitly.
+
+Unicode, emoji, RTL, CJK, and multiline input use the open-source
+[ADBKeyBoard](https://github.com/senzhk/ADBKeyBoard) broadcast contract because
+Android's built-in input command does not reliably represent those values. The
+IME must already be installed and enabled on the selected target. ADB Ready
+checks that contract before touching the screen, temporarily selects the IME,
+and restores the exact previous IME in a `finally` path. It never downloads,
+installs, enables, or leaves a keyboard selected silently. If the helper or a
+restorable current IME is unavailable, the action fails before typing.
+
+Some apps drop text delivered too quickly. Pace either backend by Unicode code
+point with a whole-millisecond delay from 0 to 2000:
+
+```bash
+adb-ready ui type 'مرحبا بالعالم' --input-mode unicode --typing-delay 40
+```
+
+### Protected input
+
+Do not put passwords or tokens in a command argument. Pipe one value to stdin:
+
+```bash
+printf '%s' "$TEST_PASSWORD" |
+  adb-ready ui fill 'id=com.example:id/password' --secret-stdin --submit
+```
+
+`--secret-stdin` reads at most 4096 bytes to EOF, removes one final line ending,
+and preserves embedded newlines. Plaintext is excluded from host process
+arguments, operation plans, terminal output, structured results, event
+journals, screenshots created by this action, and AI context. The value exists
+only in process memory and the pipe used to deliver it to the selected target.
+For Unicode, the on-device shell receives base64 rather than plaintext.
+
+This is a bounded host-side guarantee, not a secure-input claim about Android
+or the app: the selected IME and target receive the value, a normal visible
+field may display it, and device/OEM auditing can observe shell activity. Use a
+password field and assert a non-secret postcondition. A protected field cannot
+expose its value for exact verification, so ADB Ready returns
+`text-not-observable` rather than inventing success.
+
+## Keyboard and runtime-permission dialogs
+
+Inspect or dismiss the software keyboard without sending a blind Back action:
+
+```bash
+adb-ready ui keyboard status --json
+adb-ready ui keyboard dismiss
+```
+
+ADB Ready requires Android's InputMethodManager `mInputShown` state and its
+WindowInsets `type=ime` visibility to both exist and agree. `dismiss` sends Back
+only after both report visible, then reads both services again and succeeds only
+after both report hidden. An already hidden keyboard is a verified no-op.
+Missing or conflicting signals return `UI_KEYBOARD_STATE_UNSUPPORTED` or
+`UI_KEYBOARD_STATE_AMBIGUOUS`; ADB Ready does not guess from inset height or
+press Back against an unknown screen.
+
+Inspect one standard Android runtime-permission prompt before choosing an exact
+decision:
+
+```bash
+adb-ready ui permission inspect --json
+adb-ready ui permission respond allow-while-using
+adb-ready ui permission respond allow-once --dry-run --json
+adb-ready ui permission respond deny
+```
+
+Inspection returns only the decisions actually present on the current dialog.
+Responses match PermissionController package and resource IDs, never translated
+button labels or coordinates copied from another device. A fresh hierarchy must
+show that the specific prompt changed or disappeared after the tap. Multiple,
+unknown, or OEM-specific states fail closed. Notification permission setup,
+biometric prompts, Settings mutation, and generic system-dialog acceptance are
+intentionally outside this workflow.
 
 ## Find, assert, compare, and wait
 
@@ -143,8 +246,9 @@ adb-ready ui assert 'text=Loading' --state gone
 adb-ready ui compare 7c4a31b8d2ef0000000000000000000000000000000000000000000000000000
 ```
 
-`compare` consumes the complete digest returned by inspection or another UI
-action and reports whether the current hierarchy changed.
+The CLI `compare` command consumes the complete digest returned by inspection
+or another UI action and reports whether the current hierarchy changed. It
+does not persist the earlier sensitive hierarchy.
 
 Waits use exact, explicit selectors:
 
@@ -186,11 +290,31 @@ the next state is known.
 ## AI agents
 
 The MCP server exposes the same intent-level workflow through `audit_ui`, `get_ui`,
-`find_ui`, `fill_ui`, `clear_ui`, `scroll_ui`, `assert_ui`, and `compare_ui`.
+`find_ui`, `fill_ui`, `clear_ui`, `scroll_ui`, `assert_ui`, `compare_ui`,
+`inspect_keyboard`, `dismiss_keyboard`, `inspect_permission_dialog`, and
+`respond_to_permission_dialog`.
 Its structured selectors can match exact values, prefixes, or substrings and
 qualify enabled/actionable state. An optional one-based occurrence is accepted
 only when repeated nodes are intentional. Arguments are schema-validated, each
 MCP connection stays bound to one target, and no raw ADB or shell tool is
 exposed.
 
+`type_text_ui` and `fill_ui` accept `inputMode` and `typingDelayMs`. For a
+secret, set `secretEnv` to the *name* of an environment variable already passed
+to the local MCP server and omit `text`. ADB Ready reads the value locally; the
+MCP request, tool result, and retained agent conversation contain only the
+variable name. Supplying both fields, neither field, or a missing/empty variable
+fails before device mutation.
+
+`inspect_ui` retains at most eight sensitive snapshots in memory for that MCP
+connection only. `compare_ui` accepts one of those complete digests and returns
+a bounded semantic diff: added, removed, updated, and moved nodes with current
+selector context. `changed` describes the requested filtered view, while
+`digestChanged` also reveals changes outside that view. Unchanged screens return
+empty change lists. Bases expire
+after five minutes and are never written to disk; missing or expired digests
+require a fresh `inspect_ui`. A diff is rejected rather than guessed when its
+target, display bounds or rotation, hierarchy filters, acquisition contract, or
+completeness differs from the base.
+
 [Connect an agent →](./agent-integration.md)

package/examples/README.md

@@ -15,8 +15,14 @@ adb-ready dev --dry-run
 - [`flutter/adb-ready.config.json`](./flutter/adb-ready.config.json)
 - [`capacitor/adb-ready.config.json`](./capacitor/adb-ready.config.json)
 - [`custom/adb-ready.config.json`](./custom/adb-ready.config.json)
+- [`ci-emulator/`](./ci-emulator/) — maintained GitHub-hosted emulator
+  acceptance with a finite run and retained failure evidence
+- [`ci-physical/`](./ci-physical/) — manual self-hosted physical-device job
+  with explicit serial selection, host-local leasing, and bounded evidence
 - [`automation/README.md`](./automation/README.md) — one finite AVD, deployment,
   verifier, evidence, and cleanup job
+- [`target-pools/`](./target-pools/) — bounded fan-out across explicit local,
+  AVD, remote-ADB, or Firebase members
 
 Prefer `adb-ready init` when starting from an existing detected project. Add
 only the ports, hooks, and retention rules that the project genuinely needs.

package/examples/ci-emulator/README.md

@@ -0,0 +1,32 @@
+# GitHub-hosted Android emulator
+
+This fixture powers ADB Ready's maintained emulator acceptance workflow. It
+demonstrates the ownership boundary used in ordinary CI:
+
+1. the runner provisions and owns one Android emulator;
+2. ADB Ready binds a finite run to its exact serial;
+3. the fixture verifies Android boot and identity, opens Settings, and captures
+   native evidence; and
+4. ADB Ready retains normalized NDJSON, JUnit, screenshot, window, and manifest
+   evidence before the runner tears its emulator down.
+
+The workflow is [`android-emulator.yml`](../../.github/workflows/android-emulator.yml).
+Every external Action is pinned to a full commit. The job uses no repository
+secret and uploads evidence with `if: always()`.
+
+Do not copy the fixture's custom development process into an application. Keep
+your real project command and readiness assertions, then use the same bounded
+shape:
+
+```bash
+npx adb-ready run \
+  --device emulator-5554 \
+  --run-timeout 10m \
+  --json \
+  --non-interactive \
+  -- npm run test:e2e
+```
+
+ADB Ready does not implicitly create SDKs or AVDs. If another workflow layer
+created the emulator, ADB Ready attaches without claiming ownership and leaves
+emulator teardown to that layer.

package/examples/ci-emulator/adb-ready.config.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "../../schema/config-v1.schema.json",
+  "version": 1,
+  "dev": {
+    "preset": "custom",
+    "command": {
+      "executable": "node",
+      "args": ["examples/ci-emulator/dev-service.mjs"]
+    },
+    "reversePorts": [],
+    "logs": false,
+    "cleanupPorts": true,
+    "watch": true,
+    "ready": {
+      "timeoutMs": 60000,
+      "pollIntervalMs": 1000,
+      "all": [{ "kind": "boot" }, { "kind": "unlocked" }]
+    }
+  }
+}

package/examples/ci-emulator/dev-service.mjs

@@ -0,0 +1,14 @@
+let stopping = false;
+
+const keepAlive = setInterval(() => undefined, 60_000);
+
+function stop() {
+  if (stopping) return;
+  stopping = true;
+  process.stderr.write("CI development service stopped.\n");
+  clearInterval(keepAlive);
+}
+
+process.once("SIGINT", stop);
+process.once("SIGTERM", stop);
+process.stderr.write("CI development service ready.\n");