@1aboveio/skills 1.0.14 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1aboveio/skills",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "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": "5a89642fb1549c82420cbba78a75eaff01509d14cbf556480130a688e7ca1efe",
-    "releaseIdentity": "1d0affb17cf284c052ad00266f7d5ea31a7f7f9bb7f8ae6435b200835710e123"
+    "metadataDigest": "efea727f2b53be74c1dad921e4d976e9a4bf22054a5461217bea9a5983de48cc",
+    "releaseIdentity": "357a73a8819a5c43f9e6d935ece7e5efc38519d0b83e0984798677c4cb9dfc0d"
   },
   "pi": {
     "skills": [
@@ -260,7 +260,7 @@
         ]
       }
     ],
-    "digest": "ffe17fe4c3bfd5076e842358a22f58b116f060bd779f788f4ba3fd7b814f8b0e"
+    "digest": "26eb35331224e4dd2e0e8ef13bafd6383af21ae416bcf9e5acc28e68c6b45221"
   },
   "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.46.0
+release-version: 0.48.0
 ---
 **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.46.0
+release-version: 0.48.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Android development
@@ -18,7 +18,8 @@ Project rules and required CI remain binding; this skill does not add acceptance
   leaves files unchanged. Do not offer global persistence.
 - **Project**, `/android-development init`, or an explicit request to save repo conventions:
   follow [initialization](references/init.md). Preview, then apply the authorized missing
-  `CONTRIBUTING.md` section and `AGENTS.md` pointer. No second approval is needed unless
+  `CONTRIBUTING.md` section and `AGENTS.md` task-entry loader and guide pointer. Check
+  the skill loader separately from an existing guide link. No second approval is needed unless
   existing policy conflicts. Initialization is not a policy refresh or delivery permission.
 - **Session:** apply this workflow without writing guidance or agent settings. Retain the
   choice through reload/compaction in this session; a new session makes its own choice.
@@ -42,6 +43,31 @@ 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. A repo with no journey tool
+is offered Maestro for new single-device journeys; a repo with a working harness keeps it
+and adds Maestro flows alongside. 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) for the device-ownership cost, evidence layout, MCP
+use and the cases that stay custom.
+
 ## Validation ladder
 
 Read [feature work](references/feature-work.md) for selection, ownership and handoff.
@@ -122,5 +148,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
@@ -103,6 +153,11 @@ worker's "running" status does not impose a timeout or demonstrate progress. The
 whole journey. Set a positive value for unattended runs; its backward-compatible
 zero default disables that deadline. Allow time for the owner to finish cleanup.
 
+Use the harness's background-task mechanism when a journey can exceed the foreground
+command limit. Budget for the selected journey and owned cleanup; feedback-time targets
+are not kill deadlines. Continue independent work and inspect the terminal result when
+notified, rather than waiting or polling in the foreground. Do not add another watcher.
+
 For a hung test, identify the actual outstanding command and last completed assertion.
 If the test waits for a child to exit, check whether its input actually requires exit.
 Reduce that question to a bounded host test before launching another emulator.

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

@@ -30,6 +30,21 @@ Native/build-input changes invalidate that reuse; unknown compatibility calls fo
 rebuild, not an assertion that the old APK is current. Do not run `expo prebuild` routinely
 against tracked native projects.
 
+### Check journey admission before reserving devices
+
+Before an expensive native journey, verify the exact selected case and supported arguments
+against the existing runner, required installation/resource owners, effective test flags,
+and device settings. Use existing help, parser tests or preflight commands when available;
+do not invent a selector or build another preflight framework. Missing admission support
+is a harness limitation to resolve, not a reason to allocate devices and discover it later.
+Continue independent source tests while device prerequisites are checked.
+
+Apply lifecycle-changing display size, density and other required presentation settings
+before app launch when the journey relies on retaining that Activity or observation scope.
+Read back the effective settings through the existing owner. A later setting change may
+recreate the Activity; do not hide scope retirement with registration retries or relaxed
+identity checks. Keep this check scoped to the selected case, not every possible device cell.
+
 ### Verify command expansion
 
 Before adopting a native fast path, trace its package script, wrapper, Gradle tasks and

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

@@ -7,15 +7,18 @@ 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 or an unsafe target exits
-  non-zero with a message and no writes.
+- 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
+  writes, in preview and with `--write` alike.
 
 ## Files and ownership
 
@@ -27,19 +30,36 @@ to a newly created Android section; report unresolved commands instead of guessi
 | File | Write |
 | --- | --- |
 | `CONTRIBUTING.md` | The `## Android development` section, wrapped in `<!-- conventions:android:start -->` / `<!-- conventions:android:end -->`, with `references/android-conventions.md` as its body. |
-| `AGENTS.md` | A short pointer to the selected `CONTRIBUTING.md`, added only when no correct loader link exists yet. |
+| `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
 selected root.
 
 After applying authorized additions, verify that each existing supported agent entrypoint
-reaches the Android section, directly or through its instruction chain. The helper configures
+reaches both the skill task-entry instruction and the Android contributor-guide section,
+directly or through its instruction chain. A direct link to `CONTRIBUTING.md` does not
+establish that the entrypoint loads the skill rule in `AGENTS.md`. The helper configures
 `AGENTS.md`; it does not certify an independent `CLAUDE.md` loader. Preserve existing chains
 and do not edit that entrypoint under this init permission. If one does not reach the guide,
 report the files configured and the unresolved loading path as partial setup. Obtain separate
 authorization for any additional loader edit instead of silently claiming complete setup.
 
+The task-entry block requires reading and applying the installed `android-development`
+skill before Android-specific commands, during issue-unit preflight, in delegated Android
+workers, and again after compaction when its rules are lost. Keep commands and validation
+policy in `CONTRIBUTING.md`, not this loader. An existing direct read/load-before rule or
+managed block is preserved. A managed block is preserved only while it still holds an active
+loader: an empty block, or one whose only loader is commented out or written as a code example,
+is refused rather than counted as configured. A direct `do not load`-style rule that conflicts
+with the loader is refused too, wherever it sits in the file. Fenced code, indented code, HTML
+comments and inline code are documentation, so an example never counts as an active loader or as
+a conflict. An unrecognized `Android task entry` section requires manual reconciliation rather
+than a competing block. Inspect existing rules for conflicts before applying the helper; it
+cannot interpret every natural-language policy. This missing-loader addition is part of explicit
+init even in previously initialized repos, not an automatic update.
+
 ## Resolve the repo command map
 
 The initializer, not the deterministic writer, inspects existing scripts and guidance.
@@ -81,10 +101,40 @@ Existing guidance wins over the template:
 - Refuse a mutation of a multiply hard-linked file or of an alias to the protected
   `CLAUDE.md` entrypoint. This includes a shared AGENTS/CLAUDE target: preserve it and
   report the boundary rather than silently granting a new write permission.
+- Refuse an addition to a file that ends inside an unclosed fenced code block or HTML comment.
+  Appended guidance would land inside that construct, be inactive, and be appended again on
+  every run. The helper never closes it for you: preserve the manual text, repair the fence or
+  comment, and rerun. A file that needs no addition is reported unchanged, so an
+  already-configured project behind such a construct is not blocked.
 - An existing pointer is reused only when its link resolves to the selected `CONTRIBUTING.md`,
   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
@@ -92,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,7 +225,8 @@ 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

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

@@ -0,0 +1,58 @@
+# 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 | Keep the harness. Add Maestro flows for new journeys alongside it; do not migrate existing cases. |
+| Coordinated multi-device case | Keep the custom harness. Maestro sharding runs independent flows, and a shard cannot depend on another. |
+
+## Device ownership
+
+Run against the emulator the session owns and name it, so Maestro never starts or picks its
+own device:
+
+```bash
+maestro --device "$ANDROID_SERIAL" test --test-output-dir "$LOG_DIR" ./maestro-flows
+```
+
+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.
+
+## Evidence
+
+`--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:
+
+```bash
+python3 <skill-base-dir>/scripts/maestro_failure.py --maestro-dir "$LOG_DIR/2026-07-31_173617" \
+  --evidence-dir "$LOG_DIR" --case "$DEVICE_CASE"
+```
+
+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.
+
+## Agents
+
+`maestro mcp` gives an agent `list_devices`, `inspect_screen`, `take_screenshot` and `run`.
+Explore the screen and draft a flow with it; the committed YAML flow is the proof, not the
+MCP session that found the selectors.
+
+## 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.

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[@]}"