@1aboveio/skills 1.0.6 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1aboveio/skills",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Every 1aboveio skill package in one: install once, then choose which packages Pi loads with npx @1aboveio/skills select.",
   "license": "MIT",
   "repository": {
@@ -251,7 +251,7 @@
         ]
       }
     ],
-    "digest": "efb93166fdfdb1405f9a596f79d068c34b10a09ff176dc8f51021d64bd80e83d"
+    "digest": "bfce7befa948e2bb4167e5820bbebe316e25ea580c6126246d5516944520bbe0"
   },
   "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.42.1
+release-version: 0.43.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Airflow DAG Development Patterns

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

@@ -1,20 +1,22 @@
 ---
 name: android-foundation
-description: "Prove an Expo / React Native app on a native Android emulator, and fix it when that proof fails. Use before you fix and re-run or re-dispatch a failed Android CI job (`gh workflow run android.yml`, `gh run rerun`): a re-run is not a debugger, so reproduce the failing journey checkpoint off CI first. Also use when a UiAutomator journey or its Python harness tests fail (a CHECK/FAIL line, a wait that timed out, a control not found, adb offline, a lost Metro bridge, a fixture failing on the runner), to build the debug APK and run the device journey, to set up a fresh Android workspace (SDK/NDK/JDK, Gradle caches, private AVD, disposable PostgreSQL), or to add the emulator job to CI. NOT for workflow YAML, CI speed or runner design (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest component tests, or signing and store release."
-release-version: 0.42.1
+description: "Prove and debug Expo / React Native apps on an owned Android emulator. Use for stuck Android debugging, post-deploy startup or rendering failures, Metro answering while the app does not render, UiAutomator failures, missing controls, ADB drops, harness-test failures, APK builds, fresh SDK/NDK/JDK workspaces, and native journey validation. Before fixing and rerunning or redispatching a failed Android CI job, reproduce its failing checkpoint off CI: a rerun is not a debugger. Diagnose existing setups without rebuilding the whole environment. NOT for workflow YAML, CI speed or runner design (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest component tests, or signing and store release."
+release-version: 0.43.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Android foundation
 
-Take a native Expo / React Native Android workspace from a fresh checkout to a passing
-device journey, then record the evidence. Use the repo's existing build scripts, native
-project, device harness and journey wrapper. For CI, add one job to the repo's `ci.yml`
-from the template; do not write a separate release runbook.
+Prove or debug a native Expo / React Native device journey using the repo's existing
+build scripts, native project, harness and wrapper. Use `github-actions` for CI YAML
+and runner integration. The CI template is a starting point; preserve existing workflows.
 
 Pick the mode first:
 
-- **Setup proof:** a new workspace or CI job, a toolchain, dependency, native or harness
-  change, or a broken build-to-device path. Run every stage and write the
+- **Diagnosis:** an existing workspace or CI run fails or stalls. Follow
+  [Diagnosis](#diagnosis) first; a harness change does not automatically require a cold
+  setup. Re-run only the setup stages whose assumptions changed.
+- **Setup proof:** a new workspace or CI job, or a toolchain, dependency or native
+  change that invalidates setup. Run every stage and write the
   [evidence record](#evidence-record).
 - **Feature work:** proving a product change on the emulator in a workspace already set
   up. Follow [Feature work](#feature-work) and report only the journey result.
@@ -27,18 +29,24 @@ Pick the mode first:
 | Stages 6–8 in one command | [scripts/device-run.sh](scripts/device-run.sh) |
 | Adding the Android job to CI | [references/ci.md](references/ci.md), template [assets/android-ci-job.yml](assets/android-ci-job.yml) |
 | Proving a product change on the emulator | [Feature work](#feature-work) |
-| A stage failed | [Triage](#triage), then [references/gotchas.md](references/gotchas.md) |
+| A stage failed or a worker appears stuck | [Diagnosis](#diagnosis), then [references/diagnosis.md](references/diagnosis.md) and [Triage](#triage) |
 | Writing up setup proof | [Evidence record](#evidence-record) |
 
 ## Rules
 
-- Work in a dedicated worktree on a new branch from `origin/main`. Never overwrite or reuse
-  another checkout, and never symlink another worktree's `node_modules`.
+- Use an isolated checkout. For new work, branch from `origin/main`; for diagnosis,
+  pin the failed source SHA or the reviewed correction. Confirm the checkout actually
+  contains the failing code: the repo root may lag active workspaces. Never mutate a
+  peer's checkout or symlink its writable `node_modules`.
 - Tool shells keep no variables, functions or traps between calls. Write the environment
-  to `.cache/android-env.sh` once and source it at the start of every command. Run stages
-  6–8 as one `scripts/device-run.sh` command, never as separate calls.
-- Keep every cache private to the worktree under `.cache/`: Gradle home, Android user home,
-  AVD home, `TMPDIR`, npm, node-gyp and pnpm store. Keep them between runs.
+  to `.cache/android-env.sh` once and source it at the start of every command. Use the
+  repo's existing owned-resource launcher. For a new local setup without one, use
+  `scripts/device-run.sh` for stages 6–8 in one command. Do not wrap an existing owner
+  with a second emulator/database lifecycle.
+- Keep local writable caches private under `.cache/`: Gradle home, Android user/AVD
+  homes, temporary files, npm, node-gyp and pnpm. In CI, an already isolated runner slot
+  may provide those paths; verify its ownership contract rather than layering another
+  cache system on top. Never share writable state across concurrent owners.
 - Read toolchain versions from the repo: the root `packageManager` and `engines`, the
   native Gradle config, and the CI preflight. The repo is the source of truth, not this skill.
 - Check that every required SDK component (platform, build-tools, NDK, CMake,
@@ -51,8 +59,10 @@ Pick the mode first:
 - Build every configured ABI for setup proof and release acceptance. An x86_64-only CI
   APK only proves the emulator ABI. For feature work, the emulator ABI is enough unless the
   change touches native code or ABI configuration.
-- A debug APK needs Metro. A successful export or build does not prove the app works on
-  a device. Only the device journey does.
+- Determine how the selected build loads code and assets. A typical debug build needs
+  Metro; a release build normally embeds its bundle. Do not introduce Metro or debug
+  preferences into a release failure without evidence that the build uses them.
+  A successful build does not prove execution on a device.
 
 ## Stages
 
@@ -106,21 +116,64 @@ Run them in this order. Stop at the first failure and triage it.
   CID file, and the named database. Signal the PID with `TERM`, wait up to 10 seconds, then
   `KILL`. Then `wait` for it and confirm nothing is left. Count wait status 0 or 143 (ended
   by your `TERM`) as a clean stop; count a needed `KILL` or any other status as a failure.
-- Never use `adb kill-server`, `adb -s <serial> emu kill`, broad `pkill`, or
-  `docker system prune`. An ADB serial can be reused by another process; a PID you own
-  cannot.
+- Never use broad `pkill`, `docker system prune` or a shared `adb kill-server` for cleanup.
+  Use the live child's process owner, not an ADB serial that may be reused. A numeric
+  PID can also be reused after exit; it is not durable ownership evidence.
 - Give every startup, readiness and cleanup command a 30-second limit that kills the
   command's whole process group. Treat exit 124 (timeout) as a terminal failure, not as
   "not ready yet".
 - Preserve the stage's original non-zero exit status even when cleanup succeeds. Print
   `original_stage_exit=<n> cleanup_exit=<n>`.
-- After a `SIGKILL` or a host crash, the trap cannot run. Remove only this run's recorded
-  PID and container ID by hand, and keep the failure logs.
-- Point the database URL only at the disposable loopback container. Never at development,
-  production or another worker's database.
+- After SIGKILL or a host crash, verify recorded resources before recovery: process
+  start identity, command/run scope and boot identity where available, or container ID
+  and ownership labels. Never signal a numeric PID solely because an old record names
+  it. If ownership cannot be verified, leave it alone and report the gap. Keep logs.
+- For the local setup flow, point the database URL only at its disposable loopback
+  container. An existing isolated remote test flow must use its own disposable data and
+  ownership checks. Never use development, production or another worker's database for
+  fixture writes or cleanup. A public render-only smoke needs no database.
 - Expo may rewrite `android/tsconfig.json` or delete `android/expo-env.d.ts` while it runs.
   Inspect those changes and restore them before you commit.
 
+## Delivery focus
+
+Read [references/delivery-focus.md](references/delivery-focus.md) before starting or
+continuing work. Keep an existing acceptance checkpoint, reuse available evidence,
+justify new infrastructure and carry failure history across workers. Required CI and
+the full acceptance criteria still apply; report delivered behavior before activity.
+
+## Diagnosis
+
+Follow the procedure below and [references/diagnosis.md](references/diagnosis.md).
+`diagnosing-bugs`, when available, can help with deeper hypothesis testing; it is not
+required to use this skill.
+
+1. Record the failed SHA, actual checkout, build variant, device type and retained
+   evidence. Locate the earliest failing stage: build/install → launch → load code/assets
+   → initialize → render → interact. Distinguish host/CI, harness, transport and product
+   failures; an absent screen alone does not identify which one failed.
+2. Choose the smallest test that can expose the suspected defect: a host test for logic,
+   real producer/consumer composition for a contract, or a device test for native/runtime
+   behavior. Collect evidence appropriate to that stage. A service probe proves only the
+   probe, not that the application used the same path.
+3. State competing explanations and a distinguishing observation. Change one variable.
+   For reversible defects, a failure → correction → failure comparison can strengthen
+   the finding; it is optional, not a gate. For intermittent failures, use a bounded,
+   repeatable trigger and compare failure rates. Do not replay Authentication or financial
+   actions merely to obtain a comparison.
+4. Keep the first exception and its evidence separate from cleanup errors. Bound the
+   full command and each subprocess wait, allowing the resource owner time to clean up.
+   A live worker or an outstanding tool call is not evidence of progress.
+5. Verify the fix at the failing checkpoint, then run the applicable acceptance once.
+   Report local reproduction, source CI and post-deploy acceptance separately. A local
+   result on another API/ABI or a copied APK is not proof of the original CI artifact.
+
+Continue when the next attempt tests a new prediction, collects a missing observation,
+reduces the reproduction, or adds a justified sample for an intermittent failure. Name
+that purpose and bound its cost. Changing workers or repeating an unchanged run without
+such a purpose is not progress. When no available experiment distinguishes the remaining
+explanations, report the missing evidence or access instead of restarting the campaign.
+
 ## Triage
 
 Name the earliest stage that failed. In CI, that is the first failed step. If the same
@@ -135,6 +188,7 @@ the product.
 | Gradle network | Maven download or TLS-handshake errors on a cold build: fix routing, not code |
 | Emulator boot / ADB | `sys.boot_completed` never reaches 1, device offline, exit 124 |
 | Device to Metro | red box, "unable to load script", missing `adb reverse` mapping |
+| Bridge passes, debug app fails to load | possible app/probe endpoint mismatch; inspect the actual request before choosing a cause ([React Native example](references/diagnosis.md#example-react-native-debug-app-uses-another-metro)) |
 | Device to Metro, mid-journey | a screen's first Metro asset fails (`Unable to download asset from url: http://127.0.0.1:8081/assets/…`) while API calls still succeed |
 | Backend / Login | backend log errors, verification code not found in the database |
 | 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`) |
@@ -156,16 +210,20 @@ build is reliable.
 
 - Reuse the workspace's caches, venv and AVD configuration. Rerun a setup stage only when
   the change touches what it proves (toolchain, dependencies, native code, harness).
-- Build the emulator ABI and run `scripts/device-run.sh` once per candidate HEAD.
-- After a failed journey, local or a CI dispatch, reproduce the failing checkpoint off CI
-  before you run it again: in the harness unit tests with the fake UI scripted to the
-  failing screen, or on the owned emulator. Show the fix passes there, then run the journey
-  once to confirm. Never send a guessed fix to CI to see whether it passes; a failure you
-  cannot reproduce earns one more run, with added diagnostics, then goes in the report as
-  unreproduced.
-- Report the source SHA, the journey command, its `PASS` markers or the failing stage,
-  and the cleanup exit. Nothing else: no APK hash, version inventory, screenshots, copied
-  logs or earlier attempts.
+- Build the emulator ABI when its inputs changed and run the repo's owned journey
+  command once per candidate HEAD. A reused APK needs the source/configuration checks
+  the repo requires; record its hash and any provenance gap during diagnosis.
+- After a failed journey, local or a CI dispatch, enter Diagnosis mode and reproduce the
+  failing checkpoint off CI before running it again. A fake UI can reproduce a harness
+  navigation/scrolling bug; it cannot prove that the app loaded a bundle or rendered.
+  Show the fix passes at the appropriate seam, then run the journey once to confirm.
+  Never send a guessed fix to CI to see whether it passes. Use the Diagnosis continuation
+  rule for unreproduced or intermittent failures; report uncertainty until evidence
+  supports the cause.
+- For a passing feature run, report the source SHA, journey command, `PASS` markers and
+  cleanup exit. For a failure, also name the earliest failing checkpoint, link retained
+  evidence and state what remains unproved; use the diagnosis report instead of hiding
+  the failed attempts.
 - Integrated device acceptance (all ABIs, tablet, TalkBack, physical devices, a release
   device campaign) runs at the release or campaign gate the spec or repo assigns it. Do
   not recreate it per feature. Record it once, as pending, in its owning issue, never as

package/skills/app-dev/android-foundation/assets/android-ci-job.yml

@@ -107,6 +107,12 @@ jobs:
           ' "$props" "$mirror"
           grep '^distributionUrl=' "$props"
 
+      # Prerequisite: runner slots own their writable caches and Android homes.
+      # Otherwise export job-private paths to GITHUB_ENV before install so every
+      # subsequent step (including the emulator action) inherits the same paths.
+      - name: Verify writable runner isolation
+        run: <runner-cache-and-home-isolation-preflight-command>
+
       - name: Install dependencies
         timeout-minutes: 12
         run: pnpm install --frozen-lockfile
@@ -116,6 +122,7 @@ jobs:
           pnpm --filter <android-workspace-package> test
           pnpm --filter <android-workspace-package> typecheck
 
+      # Optional: only after measurement, and never for persistence/recovery tests.
       - name: Relax durability on the disposable Postgres
         env:
           PG_CONTAINER: ${{ job.services.postgres.id }}
@@ -138,9 +145,7 @@ jobs:
         timeout-minutes: 30
         env:
           EXPO_PUBLIC_API_URL: https://app.invalid
-          ANDROID_USER_HOME: ${{ github.workspace }}/.cache/android-user
         run: |
-          mkdir -p "$ANDROID_USER_HOME"
           cpus="$(nproc)"
           if [ -r /sys/fs/cgroup/cpu.max ]; then
             read -r quota period < /sys/fs/cgroup/cpu.max
@@ -148,7 +153,7 @@ jobs:
           fi
           echo "gradle max-workers=$cpus (nproc=$(nproc))"
           <android-project>/gradlew --project-dir <android-project> :app:assembleDebug --no-daemon \
-            -PreactNativeArchitectures=x86_64 --max-workers="$cpus"
+            -PreactNativeArchitectures=x86_64 -Pandroid.builder.sdkDownload=false --max-workers="$cpus"
 
       - uses: actions/setup-python@v5
         with:
@@ -172,8 +177,9 @@ jobs:
       - name: Device journey
         uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0
         env:
-          SHARD_ADMIN_URL: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/postgres
-          SHARD_DB_NAME: <ci-db-name>
+          # Replace these keys too; the harness owns their names and database prefix.
+          <harness-admin-url-variable>: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/postgres
+          <harness-db-name-variable>: <ci-db-name>
         with:
           api-level: <emulator-api>
           arch: x86_64
@@ -182,8 +188,8 @@ jobs:
           enable-hw-keyboard: true
           emulator-port: ${{ env.ANDROID_EMULATOR_PORT }}
           cores: 4
-          # At 2 GB (the usual AVD value) the guest kernel's vsock allocations fail and adb drops
-          # mid-journey, taking every adb reverse with it (references/gotchas.md).
+          # Default for this sample. The documented guest-memory ADB failure occurred
+          # on specific images; a transport drop alone does not establish that cause.
           ram-size: 4096M
           disable-linux-hw-accel: false
           script: bash <path/to/foundation-journey-wrapper.sh>

package/skills/app-dev/android-foundation/references/ci.md

@@ -1,13 +1,16 @@
 # Android CI
 
-Add an Android job to the repo's one `ci.yml`: build the debug APK and run the foundation
-journey on an emulator. Copy [assets/android-ci-job.yml](../assets/android-ci-job.yml) and
-fill every `<placeholder>`. Follow the `github-actions` skill for the `changes` job, the
-`gate` job, runner labels, pinning and hardening; this file covers only what is Android-
-specific.
+Integrate the Android build and journey into the repo's existing CI. For a new
+`changes` → area jobs → `gate` design, adapt
+[assets/android-ci-job.yml](../assets/android-ci-job.yml) and fill every placeholder.
+Use `github-actions` for workflow structure, required checks, runner labels, pinning and
+hardening. Do not replace existing required checks or workflows just to match this example.
 
 ## Wire it in
 
+The following is an example for a new gate-based workflow; retain an established repo's
+trigger and required-check contract unless changing it is part of the task.
+
 1. Add an `android` filter to the `changes` job: the app workspace, the native project,
    the backend code the journey drives, the device harness and journey scripts, the
    lockfile, and `ci.yml`. Leave docs out.
@@ -34,13 +37,18 @@ specific.
   `$GITHUB_ENV` and start the ADB server on its own port.
 - Size Gradle from the cgroup CPU quota (`/sys/fs/cgroup/cpu.max`), not `nproc`. `nproc`
   reports every host core and thrashes the native build.
+- Verify each runner slot owns its writable Gradle, Android user/AVD, temporary, npm,
+  node-gyp and pnpm state. If the runner image already isolates these, keep that contract.
+  Otherwise configure private job paths before install and export them to every later
+  step, including the emulator. A step-local Android home is insufficient.
 - Route the Gradle wrapper distribution and Maven repositories through the runner's
   dependency proxy when it has one. Fail when the proxy variable is missing; never fall
   back to direct downloads.
 
 ## Build
 
-- Build `x86_64` only (`-PreactNativeArchitectures=x86_64`), with `--no-daemon`. Report
+- Build `x86_64` only (`-PreactNativeArchitectures=x86_64`), with `--no-daemon` and
+  `-Pandroid.builder.sdkDownload=false`. Report
   this APK as emulator evidence only. The all-ABI build stays a local or release step.
 - Bundle the JavaScript with `expo export --platform android` before the native build so
   bundling errors fail fast.
@@ -49,8 +57,10 @@ specific.
 
 ## Database and journey
 
-- Run PostgreSQL as a job service on a random host port, with a health check. Turn off
-  `fsync` and `synchronous_commit` on it: the database is disposable.
+- Run PostgreSQL only when the journey needs it, as an isolated service with a random
+  host port and health check. Disable durability only when measured and when the tests
+  do not exercise recovery/persistence semantics. Discover the harness's database variable
+  names and required database prefix; map the service explicitly without shared fallbacks.
 - Run the native auth/integration tests against that service before the device journey.
 - Unit-test the device orchestration scripts (journey wrapper, slot allocator, code
   lookup) before booting the emulator.
@@ -75,11 +85,11 @@ specific.
   and whether it scrolls, and the runner's free disk at preflight. A repo that uploads no
   capture needs these in the log.
 - Upload the APK with `if-no-files-found: error`.
-- Treat one green run as one run. Fix flaky device failures at their cause instead of
-  rerunning, and do not change product code for them. An adb drop after boot means guest
-  RAM ([gotchas](gotchas.md#the-adb-transport-drops-mid-journey)). A `RemoteDisconnected`
-  with the adb transport still up means the uiautomator2 server was relaunched
-  ([gotchas](gotchas.md#remotedisconnected-right-after-a-new-process-connects)).
+- Treat one green run as one run. Investigate intermittent device failures rather than
+  retrying without a purpose. An ADB drop may match the documented guest-memory issue;
+  confirm its transport/kernel evidence before choosing that fix. `RemoteDisconnected`
+  with transport still up may match a server restart; verify server/process evidence.
+  These are hypotheses, not universal diagnoses; see [gotchas](gotchas.md).
 
 ## Traps
 

package/skills/app-dev/android-foundation/references/delivery-focus.md

@@ -0,0 +1,29 @@
+# Delivery focus
+
+Name one immediate checkpoint from the task's existing acceptance criteria: for example,
+open the app and render the expected screen. Keep that target visible while diagnosing;
+passing setup or adding helper code is not a substitute. Each independent work unit has
+its own checkpoint, so this does not serialize unrelated work.
+
+- Preserve a known-working source/artifact and relevant environment as a comparison when
+  one already exists. Do not start a baseline campaign or count that old artifact as proof
+  of the candidate. Reuse caches and valid results under the repo's ownership rules.
+- Run the smallest test that reaches the failing behavior. After it supports the fix,
+  run affected acceptance and required CI; do not repeatedly rebuild the full campaign
+  to discover the next local defect.
+- Before adding a service, transport or test abstraction, state which existing criterion
+  needs it, why the current path cannot answer the question and the smallest alternative.
+  Make routine choices within authorization; preserve shared-resource and acceptance
+  approval boundaries. Do not expand infrastructure merely because a screen failed.
+- Every continuation states the current checkpoint, new evidence or concrete blocker,
+  and the next distinguishing test. Carry prior failures across worker changes. If
+  successive attempts leave the same checkpoint unproved, reassess and reduce the case
+  or change the approach before assigning another similar attempt. Diagnostics can guide
+  that decision but do not count as delivered functionality or reset coordinator limits.
+- Report behavior delivered and criteria still unproved first. Reuse existing results for
+  time to reproduce, time to verified fix and full CI runs when available; never invent
+  those measurements or create a reporting project to obtain them.
+
+When a coordinator owns the run, keep this context in its existing plan note and worker
+result. Follow its retry/replan rules; add no separate ledger, check or acceptance gate.
+

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

@@ -0,0 +1,136 @@
+# Diagnose an existing Android failure
+
+Use the smallest investigation that can distinguish the remaining explanations. Reuse
+established resources and caches; do not build a second test platform to explain one
+failure. This procedure works without another diagnosis skill.
+
+## Locate the failing stage
+
+First identify the failed source, actual checkout, build variant, artifact provenance,
+device/API/ABI and last successful checkpoint. Do not diagnose an old repo checkout
+as though it were the running candidate. Determine whether code/assets are embedded,
+served by a development server, or delivered through another mechanism.
+
+| Stage | Useful evidence and smallest starting point |
+| --- | --- |
+| Build/install | First failing compiler, linker, dependency or package-manager operation; reproduce the affected task before booting a device |
+| Launch | Package and Activity, process start/exit, exception or crash record; use the affected device/runtime when necessary |
+| Load code/assets | Actual resource source and load result; for embedded assets inspect packaging/runtime errors, for remote assets inspect the app's actual request and response |
+| Initialize | Startup exception, configuration, service calls or producer/consumer contract; use a focused host/integration test where it reaches the defect |
+| Render | Foreground Activity, screenshot or hierarchy, runtime errors; distinguish missing rendering from a wrong selector |
+| Interact | State transitions and event ordering around the action; use a deterministic trigger or a bounded repeated lifecycle sequence |
+
+Select evidence by stage. A failed compiler does not need a screenshot. A release APK
+with embedded JavaScript does not need Metro. A physical device does not inherit the
+stock emulator's host alias. Preserve the actual failure environment when those
+properties may affect the cause.
+
+## Choose a test that can expose the defect
+
+- Use a host test when it executes the real defective logic or process lifecycle.
+- Compose the actual producer and consumer for serialization/protocol defects. Separate
+  tests with handwritten fixtures can pass while the integrated path fails.
+- Use the real app/device for native networking, rendering, Activity lifecycle, keyboard
+  or runtime behavior that a host double cannot exercise.
+
+A fake hierarchy containing the expected screen can prove selector handling, ordering
+or error classification; it cannot prove that the app loaded code and rendered that
+screen. Likewise, a service readiness probe does not establish that the app used the
+same endpoint. Observe the relevant application operation, not just its prerequisite.
+
+State competing explanations and what each predicts. Change one relevant variable
+while keeping the others fixed. A failing regression test followed by a passing
+correction may be sufficient. For a safe reversible defect, an optional A/B/A comparison
+can strengthen causal evidence: reproduce, apply one correction, restore that setting
+and see whether the failure returns. Do not make A/B/A a gate for every bug, and do not
+replay authentication, financial or other non-idempotent actions merely to obtain it.
+
+For intermittent failures, preserve the trigger conditions, record failures/attempts and
+use a bounded repeated sequence. Fix randomness or timing inputs where appropriate;
+compare baseline and corrected behavior under equivalent conditions. One passing run
+cannot establish reliability, and another sample is justified only when it answers a
+stated question. Do not claim certainty from a small sample.
+
+## Preserve evidence and resource ownership
+
+Capture the evidence needed for the failing stage before cleanup deletes it. Preserve
+the earliest exception separately from cleanup status; a cleanup timeout must not
+replace the original error. Keep raw logs private under the repo's retention rules and
+outside a checkout the next job deletes. Publish only sanitized findings. If original
+logs are gone, state that limitation rather than treating a new reproduction as the
+historical recording.
+
+Use the repository's established launcher and resource owner. Keep peers' devices,
+ports, databases and writable caches untouched. A borrowed physical device is not a
+disposable AVD: do not reset it or clear its data without task authorization. Reuse a
+shared preparation helper when callers have the same contract, while preserving
+caller-specific behavior that is actually required.
+
+A report needs the failed/tested sources, relevant artifact and environment differences,
+reproduction command, controlled change, observations, evidence locations, primary and
+cleanup outcomes, and remaining uncertainty. Do not require an APK hash for a compiler
+failure that produced no APK.
+
+## Bound work and distinguish progress from waiting
+
+Give commands and child waits explicit deadlines appropriate to their purpose. Reserve
+cleanup time and terminate only owned process groups. A force-exit option, heartbeat or
+worker's "running" status does not impose a timeout or demonstrate progress. The generic
+`device-run.sh` bounds startup/cleanup probes and supports `JOURNEY_SECONDS` for 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.
+
+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.
+
+Continue when an attempt tests a new prediction, collects a missing observation, shrinks
+the reproduction or adds a justified sample for an intermittent failure. State the
+purpose and cost bound first. When no available experiment distinguishes the remaining
+explanations, report the missing evidence/access. Do not restart an unchanged campaign
+or impose an arbitrary fixed number of retries on every kind of failure.
+
+Choose the environment the assertion requires: local test resources for ordinary
+functional diagnosis, isolated deployed HTTPS when that behavior requires it, or an
+existing shared deployment for explicitly non-destructive smoke checks. Create only the
+services needed by the test. Do not use shared dev data for destructive fixtures or
+cleanup. A request that never reaches its gateway calls for a transport investigation,
+not an assumed product fix.
+
+## Example: React Native debug app uses another Metro
+
+This example applies to a debug build that uses Metro. It is not a prescription for
+release builds, other runtimes or physical-device addressing.
+
+Record the host port, device port, reverse mapping, package and effective app settings.
+Select the private ADB endpoint before importing clients that cache it. Prove readiness,
+then observe an actual bundle request, response and screen.
+
+For RN 0.81.5, `debug_http_host` takes precedence; otherwise `metro.host` or emulator
+detection chooses the host and a compiled resource supplies the port. A stock emulator
+normally selects `10.0.2.2`. Check the pinned library and build before applying that
+explanation elsewhere. With device `tcp:8081` mapped to host `tcp:8158`, the agreed app
+endpoint might be `127.0.0.1:8081`; copying the host port into the app is not equivalent.
+Do not kill another worker's server if the app accidentally connects to it.
+
+- No owned bundle request: inspect selected address, mapping and Activity launch.
+- Request fails: inspect its response or bundling error.
+- Bundle succeeds, expected screen absent: inspect runtime exceptions, actual screen
+  and selector.
+
+In fmm-express #2001, a local API36 ARM64 comparison failed without the preference,
+rendered Login after setting it, and failed again after removing it. The original API35
+x86_64 CI response was not retained; the local HTTP 500 was not claimed as that response.
+The corrected post-deploy CI subsequently passed on its deployed SHA. Ports, package,
+cloud infrastructure and issue identifiers are case-study details, not requirements.
+
+Another repo-specific example was a Node first-login fixture with an empty Organization
+list consumed by Python. Passing the actual producer output through the real reader
+and journey seed selection exposed the mismatch before another cloud/device run. The
+general lesson is to test the composed contract, regardless of language or domain.
+
+- [Case study: issue #2001](https://github.com/1aboveio/fmm-express/issues/2001)
+- [Correction PR #2010](https://github.com/1aboveio/fmm-express/pull/2010)
+- [Passing post-deploy run](https://github.com/1aboveio/fmm-express/actions/runs/40329312705)
+- [RN 0.81.5 preference handling](https://raw.githubusercontent.com/facebook/react-native/v0.81.5/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/packagerconnection/PackagerConnectionSettings.kt)
+- [RN 0.81.5 host selection](https://raw.githubusercontent.com/facebook/react-native/v0.81.5/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/systeminfo/AndroidInfoHelpers.kt)

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

@@ -177,8 +177,10 @@ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changi
 
 ### Postgres setup hooks time out
 
-- **Cause:** durability is on.
-- **Fix:** disable `fsync` and `synchronous_commit` on the disposable service.
+- **Possible cause:** durability overhead, if timing or database logs establish it.
+- **Fix:** investigate the slow hook first. Disable `fsync` and `synchronous_commit`
+  only on a disposable service when measured and when tests do not require persistence
+  or recovery semantics. A timeout by itself does not establish this cause.
 
 ### The job never starts
 
@@ -200,11 +202,13 @@ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changi
 - **Cause:** the journey's Backend runs on the runner itself, and the self-hosted runner
   image has no browser (or other app-launched tool). A developer machine does, so it only
   fails in CI.
-- **Fix:** don't install it on the runner, and don't treat it as a product bug. Point the
-  app's browser variable (`CHROMIUM_PATH`) at a wrapper that runs the pinned Playwright
-  image's browser: `github-actions` → `references/runners.md`, "A host process that needs
-  a browser binary". Prove it in CI; Docker Desktop on macOS cannot reach the wrapper's
-  host-network port.
+- **Fix:** inspect the runner's supported browser packaging first. One option is the
+  pinned Playwright-image wrapper described by `github-actions` →
+  `references/runners.md`, "A host process that needs a browser binary". Reproduce the
+  failing command and verify the wrapper on a compatible isolated Linux environment
+  before CI acceptance; Docker Desktop on macOS cannot prove that host-network path.
+  If no compatible diagnostic environment is available, report that gap and collect
+  targeted evidence rather than sending an unverified configuration fix to CI.
 
 ### A failed run's Metro log is gone
 
@@ -215,7 +219,12 @@ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changi
 
 ## Confirm a suspected cause
 
-Inject the suspected cause on purpose, for example `adb reverse --remove tcp:8081` right
-before the failing step, and check that it reproduces the exact failure signature: the same
-step, error and error count. Then show that the fix passes the same injection. A cause that
-does not reproduce its signature is a guess, and a fix for a guess is not proof.
+Choose a test that can distinguish the suspected cause from its alternatives, as described
+in [diagnosis.md](diagnosis.md#choose-a-test-that-can-expose-the-defect). A regression test
+that reproduces the defect and passes with the correction may suffice. When safe and
+relevant, deliberate fault injection can strengthen the evidence: for example, remove a
+reverse mapping on an owned test device and compare the failure signature before and
+after the correction. Injection and A/B/A are optional techniques, not universal gates.
+For intermittent failures, compare bounded samples under equivalent conditions rather
+than requiring an identical error count. Report a cause as unconfirmed when the evidence
+does not distinguish it; do not manufacture certainty from a passing run.

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

@@ -50,6 +50,8 @@ export SETUP_AVD=<new-unique-avd-name>
 export EMULATOR_PORT=<even-port-5554-5584>
 export ANDROID_BACKEND_PORT=<free-port>
 export ANDROID_METRO_PORT=<free-port>
+# Choose the whole-journey deadline; zero disables it and is not suitable for unattended runs.
+export JOURNEY_SECONDS=<positive-journey-timeout-seconds>
 ENV
 source .cache/android-env.sh
 mkdir -p "$TMPDIR" "$npm_config_cache" "$npm_config_devdir" \
@@ -63,8 +65,10 @@ for component in platforms/android-<api> build-tools/<build-tools> ndk/<ndk> cma
 done
 ```
 
-If the wrapper reads its port or Python variables under other names, export those names in
-`android-env.sh` instead.
+If the wrapper reads ports or Python under other names, export aliases in
+`android-env.sh` **as well as** the bundled runner's required names. For example,
+`export APP_METRO_PORT="$ANDROID_METRO_PORT"`; both must select the same port. Adapt
+`DB_URL_VAR` and `DB_NAME_VAR` to the actual harness, not its fallback defaults.
 
 ## 2. Install and check
 
@@ -152,13 +156,18 @@ Pass each command as separate words, not as one quoted string. The script:
 2. Refuses an emulator port outside 5554–5584 and any busy port.
 3. Starts the ADB server, then the emulator (its PID recorded), then `postgres` with
    `--cidfile` on a random loopback port. Override the image with `POSTGRES_IMAGE`.
-4. Waits for `sys.boot_completed=1` and `pg_isready`. Every command has a 30-second limit
-   (`BOUNDED_SECONDS`) that kills the command's whole process group; exit 124 is terminal.
+4. Waits for `sys.boot_completed=1` and `pg_isready`. Startup/readiness and cleanup
+   commands have a 30-second limit (`BOUNDED_SECONDS`); exit 124 is terminal. The journey
+   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),
    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.
 
-The journey stops its own backend and Metro children. Capture the command's exit status and
-the last output line for the evidence record.
+The runner supervises the journey's process group. Journey children must stay in that
+group; a wrapper that deliberately creates detached services must stop those services
+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.