@1aboveio/skills 1.0.15 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1aboveio/skills",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Every 1aboveio skill package in one: install once, then choose which packages Pi loads with npx @1aboveio/skills select.",
   "license": "MIT",
   "repository": {
@@ -28,8 +28,8 @@
   "nativeCodex": {
     "schemaVersion": 1,
     "metadataPath": ".codex-plugin/resources.json",
-    "metadataDigest": "2bdb58dba1de073baf79efe2c5118ad75c996710344a3cde581976921c1b23ec",
-    "releaseIdentity": "a8975fa459ebba2a3e2661d861bdb9d43c072c1b01adaf41def9a93523782800"
+    "metadataDigest": "4ae04aa79316f8a7cc9df45582d19e332321316012dac6843be1eb21d2b1a385",
+    "releaseIdentity": "d4a51368dcc414b3136d3b6f51a6aeeeea77429a101eb65f36f7878e00032494"
   },
   "pi": {
     "skills": [
@@ -260,7 +260,7 @@
         ]
       }
     ],
-    "digest": "6ad0dafe4a400162776b1bf6d7c9e5ab31bf37a86d18b035fcadc4c11d06f799"
+    "digest": "ae9b2ca5b33484b68e892b41976bcc054562385ef7dc7db94bf86ab42e369d0d"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skills/app-dev/airflow/SKILL.md

@@ -2,7 +2,7 @@
 name: airflow
 description: Airflow DAG architecture and conventions. Use when designing, writing, reviewing, testing, or debugging Airflow DAGs and tasks, including TaskGroups, data intervals, timezone-aware date parameters, CLI validation, environment-based scheduling, and pytest integrity tests.
 user-invocable: true
-release-version: 0.47.0
+release-version: 0.48.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Airflow DAG Development Patterns

package/skills/app-dev/android-development/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: android-development
 description: "Prove and debug Expo / React Native apps on an owned Android emulator. Use for Android startup/rendering failures, Metro or ADB problems, UiAutomator/harness failures, APK builds, SDK/NDK/JDK workspace setup, native journey validation, and choosing Kotlin/Compose versus React Native for Android flows. Reproduce failed Android CI checkpoints off CI before fixing and redispatching. Standalone invocation offers Project or Session; init persists repo conventions. NOT for workflow YAML, CI speed or runners (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest tests, or signing/store release."
-release-version: 0.47.0
+release-version: 0.48.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Android development
@@ -43,6 +43,33 @@ Choose the task, not a fresh environment for every attempt:
   repo-specific stages in order and record proof. Do not add Expo or a new harness merely
   to match the examples, or repeat cold setup for ordinary fixes.
 
+## Device failure record
+
+A failed device case leaves one record and one line, whichever layer saw the failure:
+
+- `failure.json` holding `case`, `step`, `error`, `screenshot`, `uiDump`, `logcatTail`,
+  `evidenceDir` and `cleanupErrors`, captured at the failing step before teardown.
+- One printed line `NATIVE_FAILURE {"case":…,"step":…,"error":…,"evidenceDir":…}`.
+
+Journey code wraps its `wait_for`/`tap` helpers in
+[failure_capture.py](scripts/failure_capture.py), `with recorder.step("tap Pay"):`. Without
+that, [device-run.sh](scripts/device-run.sh) writes a partial record with `step: null` when
+the journey fails and left none. The first failure is never replaced by a cleanup error.
+The contract, other languages and the Maestro/Detox mapping are in
+[diagnosis](references/diagnosis.md#record-the-failed-device-case).
+
+## UI journey tool
+
+The skill references Maestro; it does not bundle or install it. Offer Maestro for new
+single-device journeys when the repo has no journey tool. Keep an existing sufficient
+harness; adding Maestro needs a concrete benefit and repo authorization, not just an
+installed CLI. Maestro uses the same work loop and validation ladder. Run it on the
+session's own emulator (`maestro --device <serial>`) and convert its output with
+[maestro_failure.py](scripts/maestro_failure.py), which writes the record above. Read
+[UI journeys](references/ui-journeys.md) before selecting or running Maestro flows, for
+starting state, permissions, device ownership, execution evidence and the cases that
+stay custom.
+
 ## Validation ladder
 
 Read [feature work](references/feature-work.md) for selection, ownership and handoff.
@@ -123,5 +150,7 @@ higher levels still pending rather than claiming acceptance.
 | Parallel warm servers and test-first provenance | [Parallel sessions](references/workspace.md#parallel-development-sessions) and [test-first provenance](references/feature-work.md#run-tests-before-chasing-commit-labels) |
 | Builds, provisioning, device execution, cleanup and setup proof | [setup.md](references/setup.md); use [device-run.sh](scripts/device-run.sh) only without an existing resource owner |
 | Feature/fix validation and handoff | [feature-work.md](references/feature-work.md) |
+| Device failure record and evidence capture | [diagnosis.md](references/diagnosis.md#record-the-failed-device-case) |
+| UI journey tool (Maestro) and its evidence converter | [UI journeys](references/ui-journeys.md) |
 | Failure reproduction and correction | [diagnosis.md](references/diagnosis.md), then the relevant [gotcha](references/gotchas.md) |
 | CI integration | [ci.md](references/ci.md), [template](assets/android-ci-job.yml), and `github-actions` |

package/skills/app-dev/android-development/references/diagnosis.md

@@ -94,6 +94,56 @@ reproduction command, controlled change, observations, evidence locations, prima
 cleanup outcomes, and remaining uncertainty. Do not require an APK hash for a compiler
 failure that produced no APK.
 
+## Record the failed device case
+
+Capture the failing step where it fails, not after cleanup. One contract covers every
+harness, so a coordinator, a fix brief and a later diagnosis read the same thing.
+
+`failure.json` in the evidence directory holds `case`, `step`, `error`, `screenshot`,
+`uiDump`, `logcatTail`, `evidenceDir` and `cleanupErrors`. The three artifact fields are
+file names relative to `evidenceDir`, or `null` when that capture failed; the reason then
+goes to `cleanupErrors` and never replaces `error`. Write the record once: the first
+failure is kept, and neither a later failure nor a cleanup problem overwrites it. Print
+exactly one line, `NATIVE_FAILURE {"case":…,"step":…,"error":…,"evidenceDir":…}`, so a
+reader that only sees the run output still learns the cause and where the evidence is.
+
+In Python journeys wrap the step helpers in [failure_capture.py](../scripts/failure_capture.py):
+
+```python
+from failure_capture import FailureRecorder
+
+recorder = FailureRecorder(case=os.environ["DEVICE_CASE"], evidence_dir=os.environ["LOG_DIR"])
+
+with recorder.step("tap Pay"):
+    tap("Pay")
+with recorder.step("wait for receipt"):
+    wait_for("Thank you")
+```
+
+`recorder.step` is a context manager and a decorator. On the first exception in a step it
+captures `adb exec-out screencap -p`, `uiautomator dump` and a bounded logcat tail on the
+injected serial, writes the record, prints the line and re-raises the original exception.
+Captures are bounded; a capture failure is a `cleanupErrors` entry. A cancelled run
+(`KeyboardInterrupt`, `SystemExit`) is not a failed case.
+
+Other languages implement the same two shapes. When the journey harness cannot report a
+step, fix the harness in the PR so every case records one; do not wrap it in a run-only
+script, and do not add a second failure format.
+
+Without an in-journey helper, [device-run.sh](../scripts/device-run.sh) falls back: after a
+non-zero journey exit with no `failure.json` in `LOG_DIR` it captures the screen, hierarchy
+and logcat tail before tearing the device down, writes a partial record with `step: null`,
+and prints `NATIVE_FAILURE`. Its `original_stage_exit=<n> cleanup_exit=<n>` line and exit
+status are unchanged, and a record the journey already wrote is left untouched.
+
+A repo that already runs Maestro or Detox maps its failing artifacts to this record instead
+of adding the helper: Maestro's failing-step screenshot, view hierarchy and logcat plus its
+`commands.json` step, and Detox's `failing` artifact preset output. For Maestro, run
+[maestro_failure.py](../scripts/maestro_failure.py) over the flow folder or the session folder
+it sits in; it writes the record and prints the line, and [UI journeys](ui-journeys.md#evidence)
+has the evidence layout. A record is written even when the source is the framework's artifact
+set, and the printed line still has the four fields.
+
 ## Bound work and distinguish progress from waiting
 
 Give commands and child waits explicit deadlines appropriate to their purpose. Reserve

package/skills/app-dev/android-development/references/feature-work.md

@@ -173,8 +173,9 @@ at L2. Required CI and L3 obligations remain assigned, not silently waived or ma
   rule for unreproduced or intermittent failures; report uncertainty until evidence
   supports the cause.
 - Report source SHA, commands, results and remaining gaps at review handoff. For device
-  checks, include the selected scenarios, `PASS` markers and cleanup exit. For a failure,
-  name the earliest failing checkpoint and link retained evidence; preserve failed attempts.
+  checks, include the selected scenarios, per-scenario results (`PASS` markers or the
+  journey tool's report) and cleanup exit. For a failure, name the earliest failing
+  checkpoint and link retained evidence; preserve failed attempts.
   Separate build duration, device-check duration and total worker time when discussing cost.
   Reuse existing logs to distinguish cold/warm builds, build count, ABI, test packaging,
   runtime startup and edit-to-feedback time. Do not infer a task's cost from total job time,

package/skills/app-dev/android-development/references/gotchas.md

@@ -20,8 +20,10 @@ the product.
 | Backend tool, CI only | a Backend-backed step gets a 5xx in CI only; the log names a missing program (`Browser was not found at the configured executablePath`) |
 | adb transport, mid-journey | `connection terminated: read failed` in the adb trace after boot, then lost `adb reverse`: usually guest RAM |
 | UiAutomator server | `RemoteDisconnected` while the adb transport stays up: the on-device server was relaunched |
+| Maestro driver | driver readiness fails while a setup uiautomator2 process is still alive: see [device ownership](ui-journeys.md#device-ownership) |
 | Journey harness | a wait right after a navigation times out while the destination is on screen |
 | Journey harness, short screen | a wait for a label times out only on a short or landscape screen, which shows the content above it |
+| Journey adapter | an offscreen target stays hidden while scrolls move away from it |
 | Product assertion | a screen or state mismatch with a screenshot |
 
 Then match the signal against [gotchas.md](gotchas.md). If nothing
@@ -143,6 +145,17 @@ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changi
 
 ## Journey harness
 
+### A scroll adapter moves away from the target
+
+- **Signal:** a custom comparison adapter times out on an offscreen target even though it
+  sends scroll gestures; a fake UI that exposes all targets can still pass.
+- **Cause:** Maestro's requested scroll direction describes the content to reach, not the
+  finger movement. Mapping `DOWN` to a downward finger swipe reverses the intended scroll.
+- **Fix:** for `DOWN` toward later content, swipe the finger up; for `UP` toward earlier
+  content, swipe the finger down. In the adapter test, keep the target offscreen until the
+  correct gesture moves it into view. Wrong-direction gestures must not reveal it merely
+  because a gesture count was reached. Check both directions where the adapter supports them.
+
 ### A navigation check passes on the previous screen
 
 - **Signal:** intermittently, a wait right after the next tap times out even though the

package/skills/app-dev/android-development/references/init.md

@@ -7,12 +7,14 @@ whether anything is persisted.
 ## Usage
 
 ```sh
-node {baseDir}/scripts/init.mjs [--repo-root <dir>] [--write]
+node {baseDir}/scripts/init.mjs [--repo-root <dir>] [--install-scripts [<dir>]] [--write]
 ```
 
 - Preview is the default: it prints the planned action per file and writes nothing.
 - `--write` applies the plan. `--repo-root` selects the project; without it the nearest Git root
   from the current directory is used, falling back to the current directory when there is none.
+- `--install-scripts` additionally copies the generic script layer into the repo; see
+  [Skill scripts](#skill-scripts-reference-or-copy) for the target and the rules.
 - `--help` prints the usage line.
 - An unknown argument, an unresolvable root, a malformed marker, an unsafe target or a file that
   ends inside an unclosed fenced code block or HTML comment exits non-zero with a message and no
@@ -29,6 +31,7 @@ to a newly created Android section; report unresolved commands instead of guessi
 | --- | --- |
 | `CONTRIBUTING.md` | The `## Android development` section, wrapped in `<!-- conventions:android:start -->` / `<!-- conventions:android:end -->`, with `references/android-conventions.md` as its body. |
 | `AGENTS.md` | An `Android task entry` skill-loading block between `conventions:android-task-entry` markers, plus a pointer to the selected `CONTRIBUTING.md` when missing. Check these independently: a contributor-guide link alone is not a skill loader. |
+| `<dir>/device-run.sh`, `<dir>/failure_capture.py` | Only with `--install-scripts`: the generic layer copied with a version header. |
 
 Each file is created only when it is absent. The helper never edits `CLAUDE.md`, never writes into
 a parent project, a home directory or global agent configuration, and never reaches outside the
@@ -107,6 +110,31 @@ Existing guidance wins over the template:
   and a new pointer is written relative to the real location of `AGENTS.md`. A link to some other
   file, such as a nested package guide, does not count as this project's loader.
 
+## Skill scripts: reference or copy
+
+`device-run.sh` and `failure_capture.py` are referenced from the installed skill by
+default: nothing is copied, and the run reads them from the skill directory. Copy them
+into the repo only on an explicit request, with `--install-scripts` (default target
+`scripts/android/`) or `--install-scripts <dir>` for another relative directory inside
+the project.
+
+A copy carries one header line naming the skill release and the shipped body's hash, for
+example `# android-development skill 0.47.0 sha256:<64 hex> device-run.sh`. The header
+follows a shebang or a module docstring, so neither stops being first; the rest of the file
+is the shipped script byte for byte. That makes the three outcomes unambiguous:
+
+- Missing file: `create`. An unmodified copy of the current skill: `unchanged`, so a rerun
+  writes nothing. An unmodified copy of an older skill release: `update` re-stamps the
+  header and rewrites nothing a caller added.
+- Any other content, including a copy without the header, is `drift`. It is reported in
+  preview and with `--write`, the file is preserved, and the run still succeeds. Refresh it
+  by hand; initialization never replaces a local edit.
+- Unsafe targets are refused before anything is written: an absolute path, a `..` segment,
+  or a directory whose nearest existing ancestor is a file or resolves outside the root.
+
+This is the contract's preservation rule, not an update path: a new skill release never
+rewrites project files, and drift is reported rather than resolved.
+
 ## What it does not do
 
 Initialization is not installation or delivery. It does not install dependencies, SDK components
@@ -114,7 +142,8 @@ or devices, provision an emulator, generate CI, open issues, push or release. It
 discover commands automatically: the initializer follows the command map above and reports
 what it could not resolve. Adding verified repository-specific bindings to the new section is
 part of that explicit initialization; a
-conflicting existing rule is reported rather than overwritten.
+conflicting existing rule is reported rather than overwritten. Copying the generic scripts
+does not make the repo's existing harness or CI use them.
 
 ## Scope and overrides
 

package/skills/app-dev/android-development/references/setup.md

@@ -211,7 +211,12 @@ Pass each command as separate words, not as one quoted string. The script:
    uses the separate `JOURNEY_SECONDS` deadline. Leave time for cleanup after that deadline.
 5. Exports `$DB_URL_VAR`, `$DB_NAME_VAR` (`$DB_NAME_PREFIX` plus a unique suffix) and
    `ANDROID_EMULATOR_SERIAL`, then runs the journey.
-6. Drops the database, stops the emulator PID (`TERM`, then `KILL` after 10 seconds),
+6. On a failing journey that left no record, captures the screenshot, UI dump and logcat
+   tail into `LOG_DIR` while the device is still up, writes `failure.json` with `step: null`
+   and prints one `NATIVE_FAILURE {...}` line. A record the journey's own helper wrote is
+   kept; capture problems are listed in its `cleanupErrors`. See the
+   [failure record contract](diagnosis.md#record-the-failed-device-case).
+7. Drops the database, stops the emulator PID (`TERM`, then `KILL` after 10 seconds),
    removes the container by its CID, and prints `original_stage_exit=<n> cleanup_exit=<n>`.
    It exits with the journey's status if the journey failed, else the cleanup status.
 
@@ -220,11 +225,14 @@ group; a wrapper that deliberately creates detached services must stop those ser
 through its own owner. Send TERM to the launcher and allow its cleanup to finish rather
 than killing it immediately. The generic runner inherits the caller's ADB endpoint and
 does not stop that server: use a verified private endpoint on a shared host and close it
-through the caller's owner. Capture the command's exit status and final summary line.
+through the caller's owner. Capture the command's exit status, the final summary line and,
+when the journey failed, the `NATIVE_FAILURE` line and its `failure.json`.
 
-Expect every selected scenario's `PASS` marker, screenshots, and backend and Metro logs
-when the selected variant uses those services. Preserve the failed checkpoint's evidence
-before cleanup. A release build with embedded assets does not require Metro by default.
+Expect every selected scenario's result (`PASS` marker or the journey tool's report),
+required screenshots, and backend and Metro logs when the selected variant uses those
+services. For Maestro's result and screenshot rules, read [UI journeys](ui-journeys.md#evidence).
+Preserve the failed checkpoint's evidence before cleanup. A release build with embedded
+assets does not require Metro by default.
 
 ## Owned development session
 
@@ -379,8 +387,9 @@ For setup proof only. Record:
 - Each stage's exit status and duration.
 - The APK's SHA-256 (`shasum -a 256` or `sha256sum`) and its per-ABI `lib/` entries
   (`unzip -l`), checked on the APK itself rather than inferred from Gradle flags.
-- The journey's `PASS` markers and the cleanup results: database dropped, emulator exited,
-  container removed, no listeners left on the backend or Metro ports.
+- The journey's per-scenario results (`PASS` markers or the journey tool's report) and
+  cleanup results: database dropped, emulator exited, container removed, no listeners
+  left on the backend or Metro ports.
 - Earlier failed or incomplete attempts. A later pass does not erase them.
 
 State what the run does not prove: tablet, accessibility (TalkBack), physical devices,

package/skills/app-dev/android-development/references/ui-journeys.md

@@ -0,0 +1,130 @@
+# UI journey tool: Maestro
+
+Maestro writes a single-device UI flow as YAML and records per-step failure evidence. The
+skill references it; it does not bundle or install it, and adding it is the repo's decision.
+
+## When to use it
+
+| Situation | Recommendation |
+| --- | --- |
+| Repo has no UI journey tool | Offer Maestro for new single-device journeys. It replaces hand-written adb/UiAutomator launch, poll, capture and assertion code. |
+| Repo has a working harness | Reuse it when sufficient. Add Maestro only for a concrete benefit with repo authorization; an installed CLI alone is not a reason to add or migrate journeys. |
+| Coordinated multi-device case | Keep the custom harness. Maestro sharding runs independent flows, and a shard cannot depend on another. |
+
+Maestro changes the UI journey driver, not the [work loop or validation ladder](../SKILL.md#work-loop).
+Use focused flows at the applicable L0/L1 check, candidate-APK journeys at L2, and assigned
+acceptance journeys at L3. Source tests and required backend/native checks keep their roles.
+
+## Starting state and permissions
+
+Declare each flow's intended starting app state and permissions in its YAML or owned
+fixture setup, and check included subflows and hooks for resets:
+
+- For a warm-runtime check, keep the running app or use `launchApp: {stopApp: false}`
+  to foreground it. Plain `launchApp` stops and relaunches the app by default, so it
+  cannot preserve the process whose state the check needs.
+- For restart, upgrade or fresh-install checks, use the checkpoint's required setup.
+  `clearState: true` and `clearState` clear Android app data; they do not install the
+  candidate APK or prove a fresh installation or upgrade. Clear only authorized disposable
+  state. If a reset removes debug endpoint preferences, restore them through the existing
+  owner and verify the app's actual code source before continuing.
+- Set permissions for permission-sensitive journeys. `launchApp` allows all permissions
+  by default; use the required denied or unset state to exercise denial or prompts.
+  An auto-granted run does not prove the permission-request journey.
+
+## Device ownership
+
+Run against the emulator the session owns and name it with `maestro --device <serial>`.
+Use the status handling under [Evidence](#evidence) inside the existing journey owner.
+
+Each session installs and starts Maestro's driver packages (`dev.mobile.maestro`,
+`dev.mobile.maestro.test`) through `am instrument`. That cost lands on the session's first
+flow, not on every step, so run every flow of the case in one session instead of one session
+per flow.
+
+Keep mutating checks exclusive on that device, including existing harness and Maestro
+runs. Reuse the existing runtime owner; Maestro is not a second emulator, backend or
+cleanup owner.
+
+If setup started a `setupUiAutomator` uiautomator2 process, have its owner verify ownership,
+stop it and wait for it to exit before starting Maestro; a live setup driver can block
+Maestro driver readiness. Restart that setup driver only after Maestro has fully exited,
+if it is still needed. Never stop a peer's process; coordinate with its owner instead.
+
+When comparing a custom journey adapter with Maestro, check scroll direction and prove
+offscreen targets with the [scroll-direction gotcha](gotchas.md#a-scroll-adapter-moves-away-from-the-target).
+
+## Evidence
+
+Record the selected flows, executed assertions, run exit status, app/source identity and
+cleanup outcome. Accept the harness's `PASS` markers or Maestro's per-flow results/JUnit
+report as scenario results; a zero exit with no selected flows is not a pass. For JUnit,
+use `--format junit --output <owned-report-path>`; the report is separate from
+`--test-output-dir`. Capture successful checkpoints with `takeScreenshot` when the
+assignment requires visual evidence; normal passing flows have no automatic screenshots.
+
+`--test-output-dir` receives one session folder holding one self-contained folder per flow:
+`manifest.json`, `commands.json` (one entry per executed step), the failing step's
+`screenshots/` image and `screen-hierarchy/` JSON, and `logs/device-logcat.txt`. Convert that
+into the [device failure record](diagnosis.md#record-the-failed-device-case) instead of
+adding the journey helper:
+
+Give each case/attempt a new owned `LOG_DIR`, shared with its existing launcher so its
+partial-record fallback looks in the same directory. Retain earlier attempts separately;
+reusing a runtime does not mean reusing a failure-record destination. Confirm the pinned
+Maestro supports these flags and output layout before using the example.
+
+Run this body as the existing owner's journey command. Guard both commands so `set -e`
+cannot skip conversion or cleanup after a failure. The owner retains its bounded cleanup
+after the journey exits; this is not a new launcher or an acceptance checker.
+
+```bash
+maestro_status=0
+maestro --device "$ANDROID_SERIAL" test --test-output-dir "$LOG_DIR/maestro" \
+  --format junit --output "$LOG_DIR/report.xml" ./maestro-flows || maestro_status=$?
+conversion_status=0
+python3 <skill-base-dir>/scripts/maestro_failure.py --maestro-dir "$LOG_DIR/maestro" \
+  --evidence-dir "$LOG_DIR" --case "$DEVICE_CASE" || conversion_status=$?
+printf 'maestro_exit=%s conversion_exit=%s\n' "$maestro_status" "$conversion_status"
+if [ "$maestro_status" -ne 0 ]; then
+  exit "$maestro_status"
+fi
+exit "$conversion_status"
+```
+
+Convert this invocation's finalized output before teardown. If startup or driver failure
+left no usable failed-step output, retain raw CLI logs and the original status and use
+the existing owner's partial-record fallback before cleanup. Conversion errors are
+evidence-processing failures, not replacements for the original test failure.
+
+It takes the session folder or one flow folder, writes `failure.json` into `--evidence-dir`
+(the flow folder by default) and prints the one `NATIVE_FAILURE` line for the first failed
+step. A passing flow writes nothing, and an existing record is never replaced. The artifact
+fields name the Maestro files (`screenshots/…`, `screen-hierarchy/…`, `logs/…`) rather than
+copying them into the adb names, so the failing frame and its hierarchy stay paired.
+
+Converter exit zero means processing completed, not that tests passed: a recorded failure
+also returns zero, and empty or incomplete step output may produce no record. Establish
+success from the executed assertions and per-flow results above, never from the converter
+or absence of `NATIVE_FAILURE`.
+
+## Agents
+
+`maestro mcp` gives an agent `list_devices`, `inspect_screen`, `take_screenshot` and `run`.
+Explore the screen and draft a repeatable YAML flow with it. Proof comes from executing
+the flow against the identified candidate with assertions that establish the claimed
+behavior and retained results. Committing YAML or finding selectors in MCP does not prove
+the journey passed.
+
+## Limits
+
+- Coordinated multi-device cases, exact data or payment proofs, and process-death checks stay
+  on custom harness code.
+- Authentication codes still come from the harness's disposable database, passed into a flow
+  with `maestro test -e` or resolved by its `runScript`; do not add a second fixture path.
+
+## Sources
+
+- [Launch state and permissions](https://docs.maestro.dev/reference/commands-available/launchapp)
+- [Android state clearing](https://docs.maestro.dev/reference/commands-available/clearstate)
+- [Reports and artifacts](https://docs.maestro.dev/maestro-flows/workspace-management/test-reports-and-artifacts)

package/skills/app-dev/android-development/scripts/device-run.sh

@@ -17,6 +17,13 @@
 #   POSTGRES_IMAGE (postgres:17)  DB_URL_VAR (SHARD_ADMIN_URL)  DB_NAME_VAR (SHARD_DB_NAME)
 #   LOG_DIR (.cache/logs)  BOUNDED_SECONDS (30)  BOOT_ATTEMPTS (60)  KILL_GRACE_SECONDS (10)
 #   JOURNEY_SECONDS (0 = no deadline; caller chooses a positive whole-journey limit)
+#   DEVICE_CASE (unset)  LOGCAT_LINES (400)
+#
+# A journey that fails and left no record of its own gets one before teardown:
+# $LOG_DIR/screenshot.png, $LOG_DIR/ui-dump.xml, $LOG_DIR/logcat-tail.txt and a
+# partial $LOG_DIR/failure.json with step null, plus one `NATIVE_FAILURE {json}`
+# line. A record the journey's own helper wrote is kept, and capture problems go
+# to that record's cleanupErrors instead of replacing the original failure.
 #
 # ADB_SERVER_SOCKET / ANDROID_ADB_SERVER_PORT are inherited unchanged. The caller
 # selects a private ADB endpoint before entry; this script never stops that server.
@@ -55,6 +62,7 @@ BOUNDED_SECONDS="${BOUNDED_SECONDS:-30}"
 BOOT_ATTEMPTS="${BOOT_ATTEMPTS:-60}"
 KILL_GRACE_SECONDS="${KILL_GRACE_SECONDS:-10}"
 JOURNEY_SECONDS="${JOURNEY_SECONDS:-0}"
+LOGCAT_LINES="${LOGCAT_LINES:-400}"
 
 # Reject invalid limits before creating any owned resources.
 python3 -c 'import math, sys
@@ -62,8 +70,9 @@ for value in sys.argv[1:4]:
     number = float(value)
     if not math.isfinite(number) or number < 0: sys.exit("limits must be finite and non-negative")
 if float(sys.argv[1]) == 0: sys.exit("BOUNDED_SECONDS must be positive")
-if not sys.argv[4].isdigit() or int(sys.argv[4]) < 1: sys.exit("BOOT_ATTEMPTS must be a positive integer")' \
-  "$BOUNDED_SECONDS" "$KILL_GRACE_SECONDS" "$JOURNEY_SECONDS" "$BOOT_ATTEMPTS" || exit 2
+if not sys.argv[4].isdigit() or int(sys.argv[4]) < 1: sys.exit("BOOT_ATTEMPTS must be a positive integer")
+if not sys.argv[5].isdigit() or int(sys.argv[5]) < 1: sys.exit("LOGCAT_LINES must be a positive integer")' \
+  "$BOUNDED_SECONDS" "$KILL_GRACE_SECONDS" "$JOURNEY_SECONDS" "$BOOT_ATTEMPTS" "$LOGCAT_LINES" || exit 2
 for variable in "$DB_URL_VAR" "$DB_NAME_VAR"; do
   if ! [[ "$variable" =~ ^[a-zA-Z_][a-zA-Z_0-9]*$ ]]; then
     echo "invalid database environment variable: $variable" >&2
@@ -88,6 +97,8 @@ db_ready=""
 container_started=""
 launch_in_progress=0
 pending_signal=0
+journey_started=0
+cleanup_errors=()
 handle_signal() {
   pending_signal="$1"
   # Do not abandon a spawned supervisor before its PID has been recorded.
@@ -174,8 +185,86 @@ managed() {
 
 bounded() { managed "$BOUNDED_SECONDS" "$@"; }
 
+capture_artifact() {
+  # capture_artifact <file-name> <adb args...>; an empty capture is not evidence.
+  local name="$1" file="$LOG_DIR/$1"
+  shift
+  if bounded adb -s "$ANDROID_EMULATOR_SERIAL" "$@" > "$file" 2>/dev/null && test -s "$file"; then
+    return 0
+  fi
+  cleanup_errors+=("$name: adb -s $ANDROID_EMULATOR_SERIAL $* produced no evidence")
+  rm -f "$file"
+}
+
+capture_ui_dump() {
+  local remote=/sdcard/android-failure.xml file="$LOG_DIR/ui-dump.xml"
+  if bounded adb -s "$ANDROID_EMULATOR_SERIAL" shell uiautomator dump "$remote" >/dev/null 2>&1 \
+    && bounded adb -s "$ANDROID_EMULATOR_SERIAL" exec-out cat "$remote" > "$file" 2>/dev/null \
+    && test -s "$file"; then
+    return 0
+  fi
+  cleanup_errors+=("ui-dump.xml: adb -s $ANDROID_EMULATOR_SERIAL shell uiautomator dump failed")
+  rm -f "$file"
+}
+
+capture_logcat() {
+  # An empty tail is still a capture; a failed one is not.
+  local file="$LOG_DIR/logcat-tail.txt"
+  if bounded adb -s "$ANDROID_EMULATOR_SERIAL" logcat -d -t "$LOGCAT_LINES" > "$file" 2>/dev/null; then
+    return 0
+  fi
+  cleanup_errors+=("logcat-tail.txt: adb -s $ANDROID_EMULATOR_SERIAL logcat -d -t $LOGCAT_LINES failed")
+  rm -f "$file"
+}
+
+write_failure_record() {
+  local error
+  case "$1" in
+    124) error="journey exceeded ${JOURNEY_SECONDS}s (status 124): ${journey_cmd[*]}" ;;
+    *) error="journey exited with status $1: ${journey_cmd[*]}" ;;
+  esac
+  # One writer for the record and its line, so their shapes cannot drift.
+  python3 - "$LOG_DIR" "${DEVICE_CASE:-}" "$error" \
+    ${cleanup_errors[@]+"${cleanup_errors[@]}"} >&3 <<'PY' || {
+import json, os, sys
+evidence, case, error = os.path.abspath(sys.argv[1]), sys.argv[2] or None, sys.argv[3]
+record = {"case": case, "step": None, "error": error}
+for key, name in (("screenshot", "screenshot.png"), ("uiDump", "ui-dump.xml"), ("logcatTail", "logcat-tail.txt")):
+    path = os.path.join(evidence, name)
+    record[key] = name if os.path.isfile(path) and os.path.getsize(path) else None
+record["evidenceDir"] = evidence
+record["cleanupErrors"] = sys.argv[4:]
+path = os.path.join(evidence, "failure.json")
+temporary = path + ".tmp"
+with open(temporary, "w", encoding="utf-8") as stream:
+    stream.write(json.dumps(record, indent=2) + "\n")
+os.replace(temporary, path)
+print("NATIVE_FAILURE " + json.dumps(
+    {key: record[key] for key in ("case", "step", "error", "evidenceDir")}, separators=(",", ":")))
+PY
+    echo "failure record not written; keep the evidence in $LOG_DIR" >&3
+    return 0
+  }
+}
+
+capture_failure() {
+  # Called before teardown: the emulator and app are still in the failing state.
+  local status="$1" cancelled="$2"
+  test "$status" -ne 0 || return 0
+  test "$journey_started" -eq 1 || return 0
+  # A requested stop is not a failed case.
+  test "$cancelled" -eq 0 || return 0
+  # The journey's own helper already recorded the failing step; keep that record.
+  test ! -e "$LOG_DIR/failure.json" || return 0
+  capture_artifact screenshot.png exec-out screencap -p
+  capture_ui_dump
+  capture_logcat
+  write_failure_record "$status"
+}
+
 cleanup() {
   original_status=$?
+  cancelled_signal="$pending_signal"
   trap - EXIT
   trap '' INT TERM
   pending_signal=0
@@ -187,6 +276,7 @@ cleanup() {
     wait "$active_pid" || :
     active_pid=""
   fi
+  capture_failure "$original_status" "$cancelled_signal"
   if test -n "$db_ready"; then
     bounded "${drop_cmd[@]}" || cleanup_status=1
   fi
@@ -279,4 +369,5 @@ export "$DB_URL_VAR=postgresql://postgres:postgres@127.0.0.1:$db_port/postgres"
 export "$DB_NAME_VAR=${DB_NAME_PREFIX}$(date +%s)_$$"
 db_ready=1
 
+journey_started=1
 managed "$JOURNEY_SECONDS" "${journey_cmd[@]}"