adb-ready 0.4.1 → 0.5.0

package/docs/agent-integration.md

@@ -147,7 +147,10 @@ unambiguous paired service; it never guesses among multiple devices.
 
 Tool calls within one MCP connection are executed in submission order. This
 prevents parallel agent requests from interleaving target binding, UI snapshots,
-or device mutations. Separate MCP connections remain independent.
+or device mutations. Separate MCP connections remain independent, while the
+short Android hierarchy-capture step is additionally serialized per target
+across connections and processes because the platform exposes only one active
+UI Automation service per target.
 
 ## Tool surface
 

package/docs/automation.md

@@ -32,6 +32,12 @@ Root presentation flags may appear in either order. Adding
 `--non-interactive` does not change the result shape or fall back to human
 help.
 
+Version probes follow the same rule without loading configuration or ADB:
+`adb-ready version` and `adb-ready --version` print one conventional bare
+version line, while `version --format plain`, `version --json`, and
+`version --format ndjson` return their documented automation shapes. Output
+flags may appear before or after `version` or `--version`.
+
 Machine data is written to `stdout`. Human progress and diagnostics are written
 to `stderr`. `--quiet` hides successful human output without hiding failures.
 
@@ -125,10 +131,25 @@ adb-ready init --dry-run --json
 adb-ready connect 192.168.1.42:37123 --dry-run --json
 adb-ready ports reverse add 8081 --dry-run --json
 adb-ready dev --port 8081 --dry-run --json
+adb-ready run --avd Pixel_9_API_36 --deploy --dry-run --json -- maestro test smoke.yaml
 ```
 
 Plan steps declare their risk. A dry run performs no pairing, connection,
-mapping, hook, or child-process mutation.
+mapping, hook, deployment, or child-process mutation. `dev` and `run` plans are
+compiled offline even when `--device`, `--transport-id`, `--last`, `--select`,
+or `--avd` is present: ADB Ready does not contact the ADB server, inspect a
+target, start an emulator, resolve an artifact, launch the project, or execute
+the verifier. Target selectors and artifact paths remain declarative inputs in
+the plan and are validated only during an actual run.
+
+Port endpoints are always named by their role. Forward mappings listen on the
+host and route to the selected device; reverse mappings listen on the device
+and route back to the host:
+
+```bash
+adb-ready ports forward add 9229 3000 --dry-run  # host 9229 -> device 3000
+adb-ready ports reverse add 8081 3000 --dry-run  # device 8081 -> host 3000
+```
 
 ## Run one bounded verification
 
@@ -163,6 +184,50 @@ Preview the complete project plan before a device is allocated:
 adb-ready run --preset expo --dry-run --json -- npm run test:e2e
 ```
 
+### Start an existing AVD and deploy the intended build
+
+For a complete local or CI-owned emulator job, name one existing AVD and either
+provide the intended artifact or let ADB Ready discover exactly one compatible
+build output:
+
+```bash
+adb-ready run \
+  --avd Pixel_9_API_36 \
+  --artifact android/app/build/outputs/apk/debug/app-debug.apk \
+  --package com.example.app \
+  --run-timeout 10m \
+  -- maestro '--device={target.serial}' test .maestro/smoke.yaml
+
+adb-ready run --avd Pixel_9_API_36 --deploy --variant debug -- \
+  ./gradlew connectedDebugAndroidTest
+```
+
+The AVD must already exist. ADB Ready uses the standard Android Emulator and
+ADB tools as its portable baseline; it does not create, delete, or upgrade an
+SDK or AVD. An already-running matching emulator is reused and never stopped.
+An emulator started by this run is readiness-checked and stopped on success,
+failure, cancellation, or timeout.
+
+Artifact selection prefers Android build metadata and refuses ambiguous,
+incomplete, incompatible, outside-project, or stale candidates. APK and split
+APK sets install directly. APK Set and Android App Bundle deployment requires
+an explicit or locally verified bundletool; ADB Ready never downloads one in
+the background. The installed package, version, ABI compatibility, and launch
+activity are independently verified before the project or verifier runs.
+
+During an interactive run, the terminal shows target inspection, artifact
+selection, and install verification as distinct live steps. The final summary
+identifies the artifact kind, variant, file count, package, version, launch
+activity, and whether a requested emulator was started or reused. Local
+artifact paths remain in the redacted evidence bundle instead of being exposed
+in the compact human summary. `--plain` exposes the same result as stable
+line-oriented `artifact_*`, `deployment_*`, and `emulator_*` fields; `--json`
+and `--ndjson` retain the complete structured automation data.
+
+The evidence manifest also includes the verifier's bounded, redacted native
+stdout and stderr. Preparation failures still publish the same result,
+problems, JUnit, and evidence contract after owned-resource cleanup.
+
 ## CI example
 
 ```yaml

package/docs/dev-sessions.md

@@ -55,6 +55,25 @@ One selected transport is used for the entire session:
 Use `--device`, `--transport-id`, `--last`, or `--select` to override the normal
 selection policy.
 
+## App-scoped crash diagnostics
+
+Set the Android application ID when project detection cannot prove it:
+
+```bash
+adb-ready dev --package com.example.app
+```
+
+The same value can be shared as `app.android.package` in project configuration.
+ADB Ready verifies the package on the selected target and filters logcat by its
+restart-stable UID when supported, with an exact PID fallback for older
+targets. Expo sessions automatically switch to the package Android resolves
+for the verified Expo Go or development-client launch URL.
+
+Until that identity is verified, startup records remain explicitly
+`log.unattributed`. They can help reconstruct a target timeline, but an
+unrelated system or test-process crash cannot become an application problem or
+outrank attributed evidence in exported AI context.
+
 ## Port ownership
 
 The session treats each requested mapping as one of three states:
@@ -87,6 +106,14 @@ Detection is deliberately bounded:
 - an explicit mapping for the same device port always wins; and
 - cleanup still removes only mappings created by the current session.
 
+ADB's `tcp:PORT` reverse endpoint connects to host localhost, while host
+toolchains may resolve `localhost` to either IPv4 or IPv6. ADB Ready probes both
+loopback families. If a required service listens only on `[::1]`, it creates a
+session-owned proxy on `127.0.0.1` for the same port so the selected Android
+target can use the normal reverse mapping. The proxy is loopback-only, remains
+owned by the session that created it, and is closed during session cleanup. ADB
+Ready fails safely if that bridge cannot be created.
+
 Preview the resolved mappings without touching ADB:
 
 ```bash
@@ -107,8 +134,9 @@ The same switch is available to `adb-ready init`. It can also be persisted as
 
 For Expo and React Native, ADB Ready checks the local host behind the default
 device port `8081` before launching the project command. It attaches only when
-`/status` returns Metro's exact running-status response. An open port alone is
-not sufficient evidence.
+`/status` returns Metro's exact running-status response and Expo identifies the
+same canonical project root. An open port, an unidentified Metro server, or a
+Metro server belonging to another project is not sufficient evidence.
 
 An attached Metro server remains externally owned:
 
@@ -120,10 +148,13 @@ An attached Metro server remains externally owned:
   never restarts a process ADB Ready does not own.
 - A non-Metro service on the configured host port fails with
   `DEVELOPMENT_SERVICE_CONFLICT` and an actionable explanation.
+- A Metro server with a missing or different project identity fails with the
+  same safe conflict and remains untouched.
 
-Run Metro in its original terminal when you need its native reload or developer
-controls. A newly started Metro process continues to receive its controls
-directly through ADB Ready.
+Run an externally owned Metro server in its original terminal when you need its
+native controls. When ADB Ready starts and owns an Expo session, it activates
+its own verified controls after the app and local Expo control channel are
+ready.
 
 ## Expo target isolation
 
@@ -203,21 +234,23 @@ Set `dev.watch` to `false` only for a deliberately one-shot child process.
 ## Live terminal controls
 
 An interactive `adb-ready dev` session shows a compact control bar after it
-becomes ready. ADB Ready preserves the framework's native terminal input rather
-than intercepting or redefining it:
-
-- Expo shows `r` reload, `m` developer menu, `j` debugger, and `?` commands.
-- Flutter shows `r` hot reload, `R` hot restart, and `h` commands.
-- Other presets state that framework input is active without promising
-  unsupported shortcuts.
+becomes ready. The bar advertises only controls that ADB Ready has activated and
+can execute itself:
+
+- An owned Expo session supports `r` to reload the connected app, `m` to open
+  its developer menu, and `?` to show the exact controls again. These actions
+  use Expo's local message protocol only after ADB Ready verifies the loopback
+  Metro endpoint and an active control connection.
+- An attached Metro server remains externally owned, so its controls stay in
+  the terminal that started it.
+- Other presets show no unverified framework shortcuts.
 - `Ctrl+C` stops the owned child and performs the normal verified cleanup.
 - Health monitoring is stopped and awaited before intentional child or port
   teardown, so cancellation cannot be recorded as a device degradation or a
   recovery attempt.
 
 The control bar is never rendered by `run`, JSON/NDJSON output, redirected
-streams, CI, `--non-interactive`, or `--quiet`. This keeps scripts deterministic
-and leaves arbitrary child input untouched.
+streams, CI, `--non-interactive`, or `--quiet`. This keeps scripts deterministic.
 
 ## Lifecycle hooks
 

package/docs/logs-and-context.md

@@ -51,7 +51,16 @@ follow boundary so records written during setup are neither lost nor repeated.
 Unparsed lines are preserved. Output arriving on `stderr` is not automatically
 classified as an error; severity comes from source semantics. Fatal Android
 exceptions, native crashes, ANRs, and React Native fatal errors become
-structured findings.
+structured findings. Package-scoped streams first verify the installed package
+identity, prefer Android's restart-stable UID filter when the selected target
+supports it, and fall back to the package's current PID on older targets.
+
+Development sessions do not infer application ownership from a broad tag such
+as `AndroidRuntime`. Before an application identity is verified, matching
+target-wide records are retained as low-priority `log.unattributed` evidence
+and never promoted to application problems. A configured `app.android.package`
+or `dev --package APP_ID` scopes the stream directly; Expo sessions retarget it
+to the package that Android resolves for the verified launch URL.
 
 ## Session history
 
@@ -81,6 +90,14 @@ When the ID is omitted, the latest saved session is selected. Default retention
 keeps at most 30 finalized sessions, 14 days, and 20 MiB. Active sessions are
 not pruned as finalized history.
 
+Running-session summaries are reconciled from the append-only event journal at
+read time. `sessions list`, `sessions show`, and `context` therefore expose the
+latest completely persisted event count, byte count, update time, and known
+preset without rewriting the manifest for every log line. A trailing event
+that is still being appended is ignored until its terminating newline is
+durable, so concurrent inspection never treats a partial JSON record as a
+corrupt session.
+
 Storage locations follow host conventions:
 
 | Host | Default directory |

package/docs/targets-and-wireless.md

@@ -28,6 +28,12 @@ adb-ready devices --last
 disambiguates duplicate transports. `--last` resolves the last verified target
 identity; it does not silently choose an unrelated visible device.
 
+An exact serial, serial-backed alias, or transport ID also bounds target-side
+identity inspection to that transport. ADB Ready does not query unrelated
+visible devices before running the requested command. Stable hardware-identity
+selection and remembered-target recovery inspect the inventory because those
+workflows must correlate a target whose transport may have changed.
+
 All target-aware commands accept the same selectors.
 
 ## Pair Android 11 and newer

package/docs/troubleshooting.md

@@ -31,6 +31,8 @@ adb-ready context --since 5m --only problems,recovery,logs
 | `MULTIPLE_WIRELESS_ENDPOINTS` | Discovery returned ambiguous services | Pass one exact `HOST:PORT` |
 | `PORT_MAPPING_CONFLICT` | Another mapping owns the requested listen port | Inspect `ports ... list`; remove or change it explicitly |
 | `LOG_PACKAGE_NOT_RUNNING` | Package filtering could not resolve a live process | Launch the app or use another package/PID |
+| `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 |
 | `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 |

package/docs/ui-automation.md

@@ -23,6 +23,13 @@ UI Automator waits for a quiet accessibility window before returning data.
 quiet window; pause the changing UI or navigate to a stable screen and retry.
 ADB Ready does not silently disable device-wide animations.
 
+Android permits only one active UI Automation service on a target. ADB Ready
+therefore serializes the short hierarchy-capture step per target, including
+across separate CLI and MCP processes. Independent targets still run in
+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.
+
 ## Audit one screen for people and agents
 
 ```bash

package/examples/README.md

@@ -15,6 +15,8 @@ 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)
+- [`automation/README.md`](./automation/README.md) — one finite AVD, deployment,
+  verifier, evidence, and cleanup job
 
 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/automation/README.md

@@ -0,0 +1,24 @@
+# Autonomous Android verification
+
+Preview the complete workflow without starting an emulator, installing an app,
+or launching a process:
+
+```bash
+adb-ready run \
+  --avd Pixel_9_API_36 \
+  --artifact android/app/build/outputs/apk/debug/app-debug.apk \
+  --package com.example.app \
+  --dry-run \
+  --json \
+  -- maestro '--device={target.serial}' test .maestro/smoke.yaml
+```
+
+Remove `--dry-run` to execute the verified job. Use `--deploy --variant debug`
+instead of `--artifact` when the project contains exactly one compatible debug
+artifact. ADB Ready refuses ambiguous outputs instead of selecting by filename
+or modification time.
+
+The verifier is invoked directly, receives the same target in `ANDROID_SERIAL`
+and `ADB_READY_TARGET_SERIAL`, and retains its bounded output in the run's local
+evidence bundle. A matching emulator that was already running is left running;
+only an emulator started by this invocation is stopped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adb-ready",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   "private": false,
   "type": "module",

package/schema/agent-tools-v1.json

@@ -1,7 +1,7 @@
 {
   "title": "ADB Ready agent tool contract",
   "schemaVersion": 1,
-  "packageVersion": "0.4.1",
+  "packageVersion": "0.5.0",
   "protocolVersion": "2025-11-25",
   "transport": "stdio",
   "tools": [