@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,221 @@
+# Android foundation gotchas
+
+Known traps, each as signal, cause and fix. Match the signal before you dig. If none
+matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changing code.
+
+## Emulator and AVD
+
+### A hand-written AVD misses the screen
+
+- **Signal:** taps or swipes land nowhere, or a control below the fold never scrolls into
+  view, though the same journey passes elsewhere. The device reports `Physical size:
+  320x480`.
+- **Cause:** `config.ini` was written from scratch without the hardware keys. Without
+  `hw.lcd.*` the emulator defaults to 320x480, so a journey's display override and fixed
+  coordinates no longer match.
+- **Fix:** copy the hardware keys from an `avdmanager`-made AVD on the same runner:
+  `hw.lcd.width`, `hw.lcd.height`, `hw.lcd.density` and `disk.dataPartition.size`. Set
+  `hw.ramSize=4096` instead of copying its value; see
+  [adb transport drops](#the-adb-transport-drops-mid-journey).
+
+### `avdmanager` cannot see an installed image
+
+- **Signal:** `avdmanager create avd --package …` fails with `Package path is not valid` and
+  lists only the images under its own SDK.
+- **Cause:** `avdmanager` derives its SDK root from its own install location. It ignores
+  `ANDROID_SDK_ROOT` and `ANDROID_HOME`, so an image under another root (a slot-local
+  overlay, for example) is invisible to it.
+- **Fix:** write the AVD's `.ini` and `config.ini` yourself, with `image.sysdir.1` relative
+  to the SDK root the emulator uses. Then apply
+  [the hardware keys](#a-hand-written-avd-misses-the-screen). An image that ships a `data/`
+  tree instead of `userdata.img` is fine: the emulator seeds userdata from it on first
+  boot.
+
+### The emulator boots in software
+
+- **Signal:** boot takes 10+ minutes.
+- **Cause:** KVM is unusable to the emulator. A host where `test -r/-w /dev/kvm` passes but
+  Node's `fs.accessSync(R_OK | W_OK)` fails still falls back to software.
+- **Fix:** check KVM with `accessSync` in the preflight, and set
+  `disable-linux-hw-accel: false`.
+
+### Two jobs fight over `emulator-5554` or Metro's port
+
+- **Cause:** runner slots share the host network, and the ports are not slot-derived.
+- **Fix:** derive the ADB server, emulator console, backend and Metro ports from the slot
+  number ([ci.md](ci.md#runner)).
+
+## Metro and adb
+
+### Lost `adb reverse`
+
+- **Signal:** earlier steps passed, then a screen's first Metro asset fails: `Unable to
+  download asset from url: http://127.0.0.1:8081/assets/…`, often an icon font. With
+  `expo-font`/`expo-asset`, every mounted icon reports a rejection (a burst of a dozen or
+  more). API calls on the same screen still succeed.
+- **Cause:** an adb transport reconnect keeps the emulator in `device` state but deletes
+  every `adb reverse` mapping; `adb reverse --list` comes back empty. UI automation
+  recovers, Metro becomes unreachable, and a debug build loads assets from Metro. A
+  backend reached at `10.0.2.2` does not use adb, so it keeps working. The usual trigger is
+  an [adb transport drop](#the-adb-transport-drops-mid-journey); fix that first.
+- **Fix:** re-prove the bridge before every step whose screen is the first to load a Metro
+  asset: re-apply the reverse and check, from inside the device, that Metro answers. Doing
+  it only at app launch is not enough. Release builds embed their assets, so this is a
+  harness failure, not a product failure.
+
+### The adb transport drops mid-journey
+
+- **Signal:** the host adb server's transport trace (`ADB_TRACE=transport`) shows
+  `remote local: terminated (data)` then `emulator-NNNN: connection terminated: read
+  failed` after boot, while the emulator stays up. About 0.5 s later the device is back
+  in `device` state, but [every `adb reverse` is gone](#lost-adb-reverse). Steps fail at
+  random, often during bursts of guest-to-host data (`dumpsys`, hierarchy dumps,
+  logcat). A drop during boot, before `sys.boot_completed`, is normal: adbd restarts once.
+- **Cause:** guest memory, seen on x86_64 API 35/36 images with `android15-6.6` kernels
+  6.6.50 and 6.6.66. GKI `android15-6.6-2025-09` and later cap these pieces at about
+  28 KiB, which should avoid it, but no emulator image with such a kernel was tested. The guest kernel sends adb
+  data over virtio-vsock in pieces of up to 64 KiB, each needing one contiguous 128 KiB
+  allocation. At 2 GB (the usual AVD value), a busy journey fragments guest memory until that
+  allocation fails. adbd's `write()` gets `ENOMEM` (`error 12: Out of memory`), adbd
+  treats it as fatal, logs `connection terminated: write failed` and closes the transport
+  itself, so the host side is not the cause. In the traced runs only the job's own adb
+  server was connected to the emulator.
+- **Fix:** give the guest 4 GB: `hw.ramSize=4096` in the AVD's `config.ini`, replacing any
+  existing value. At 4 GB the guest kept 127+ free blocks of 128 KiB or larger, with no
+  allocation stalls and no drops; at 2 GB it fell to 1 such block, with hundreds of
+  stalls. Keep re-proving `adb reverse` before Metro-dependent steps as a safety net.
+- **Confirm:** with `adb root`, set `persist.adb.trace_mask=rwx,transport`, restart
+  adbd, and look for `writex: fd=N error 12` in `/data/adb/adb-*`. Guest tracepoints
+  `vsock/virtio_transport_{alloc,recv}_pkt` show adbd's own `SHUTDOWN` going out first;
+  `/proc/buddyinfo` shows order-5 and larger blocks (128 KiB+ contiguous) near zero.
+- **Dead ends:**
+  - `-feature -VirtioVsockPipe`: adb stays `offline` forever on API 35.
+  - adb over TCP through the emulator console's `redir`: works only on boots where guest
+    `eth0` gets `10.0.2.15`.
+  - A newer emulator or platform-tools: no relevant fix in their release notes.
+
+### `RemoteDisconnected` right after a new process connects
+
+- **Signal:** the first uiautomator2 RPC in a newly started Python process raises
+  `RemoteDisconnected`. The adb transport stays registered: the trace shows `tcp:9008`
+  refused (`OPEN` then immediate `CLSE`), then a single stream `CLSE` with no response,
+  and no `connection terminated`.
+- **Cause:** uiautomator2 keeps its on-device server inside an adb shell session owned by
+  the Python process that started it. When that process exits the server dies, and the
+  next process relaunches it. An RPC sent while it starts gets cut off, especially with
+  uiautomator2's own restart and retry bypassed.
+- **Fix:** drive the whole journey from one process, or wait until the server answers
+  `/ping` before the first RPC. This is not an [adb drop](#the-adb-transport-drops-mid-journey).
+
+## Journey harness
+
+### A navigation check passes on the previous screen
+
+- **Signal:** intermittently, a wait right after the next tap times out even though the
+  app works. The screen at failure is the destination of the previous navigation, often
+  scrolled by the harness's own swipes, and the app records no navigation for that tap.
+- **Cause:** the check that should confirm arrival also matches text on the origin
+  screen, so it passes before the new screen lands. The next tap then hits the screen
+  mid-transition and is sometimes lost.
+- **Fix:** after a navigation, wait for something only the destination shows, such as its
+  own record ID next to its label, never a value the origin also displays. To prove it,
+  make the unit tests' fake UI (the scripted hierarchy the harness tests read) keep the
+  origin on screen for a few reads and drop taps in that window; the test must fail
+  without the fix.
+- **Example:** after `Original Payment Transaction` on a refund, the check waited for the
+  original's Provider Reference, which the refund also shows as `Parent Provider
+  Reference`. `Back to History` landed about 75 ms into the transition, and about one
+  cold run in three failed with `Timed out: return to History list`. Waiting for the
+  original's `Payment Transaction ID` fixed it.
+
+### A wait never scrolls to its label
+
+- **Signal:** a wait for a label times out only on a short or landscape screen (812x360,
+  for example) and passes on the phone. The screen at failure shows the content above the
+  label.
+- **Cause:** UiAutomator lists only nodes that are on screen, and the wait checks the
+  hierarchy without scrolling. On a short screen the label sits below the fold.
+- **First:** check `adb shell wm size`. A 320x480 screen is
+  [a hand-written AVD](#a-hand-written-avd-misses-the-screen), not this.
+- **Fix:** scroll toward the label before or while waiting. To prove it, make the harness
+  test's fake UI keep the label off screen until a scroll; the test must fail without the
+  fix.
+
+### A harness test fails on the runner's real state
+
+- **Signal:** a harness unit test fails before the APK builds with a host-resource message
+  (`Retained native owner requires 2 GiB reserve`), and passes on a developer machine.
+- **Cause:** the code under test reads real host state (free disk, SDK paths) that the
+  fixture does not fake, and the runner's state differs from the developer's.
+- **Fix:** fake that state in the fixture. Then check the runner itself: a slot below the
+  threshold fails the real journey too.
+
+### A new journey fails in the commit that adds it
+
+- **Signal:** a journey added or changed in this commit fails waiting for a screen (`Select
+  your Store`) that the app no longer shows; the screen at failure shows the current app.
+- **Cause:** often the journey was written against the old screen. A product regression
+  that only this journey exercises shows the same signal.
+- **Fix:** read the screen at failure and the commit's product diff before choosing. If the
+  app shows the intended screen, update the journey; never change product code to match
+  a journey.
+
+## CI runners
+
+### The Android check is cancelled on the exact head
+
+- **Signal:** the queue reads the cancelled check as failing.
+- **Cause:** GitHub can deliver one push as two identical `pull_request` events.
+- **Fix:** if Android has its own workflow, key `concurrency.group` on `github.run_id`
+  with `cancel-in-progress: false`.
+
+### The native build takes ~20 minutes on an 8-CPU slot
+
+- **Cause:** Gradle saw every host core.
+- **Fix:** size `--max-workers` from the cgroup quota (`/sys/fs/cgroup/cpu.max`), not
+  `nproc`.
+
+### Postgres setup hooks time out
+
+- **Cause:** durability is on.
+- **Fix:** disable `fsync` and `synchronous_commit` on the disposable service.
+
+### The job never starts
+
+- **Cause:** no online runner carries the label set.
+- **Fix:** see the `github-actions` runner guide.
+
+### `setup-java` or `setup-python` takes 10+ minutes on a new runner slot
+
+- **Cause:** the slot's tool cache is empty, so the JDK or Python downloads from the
+  internet.
+- **Fix:** seed the runner's `_tool/` directory from a sibling slot with the same image.
+
+### A Backend call fails only in CI: the runner lacks a tool the app launches
+
+- **Signal:** the journey passes locally but in CI a step that reaches the Backend
+  (receipt email, PDF share, export) gets a 5xx, and the backend log names a missing
+  program, e.g. `Receipt PDF generation failed: Browser was not found at the configured
+  executablePath`.
+- **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.
+
+### A failed run's Metro log is gone
+
+- **Cause:** the journey writes raw service logs under the checkout (`test-results/`), and
+  the next job's checkout removes them.
+- **Fix:** for a diagnosis, copy the Metro log and a full `adb logcat` to persistent
+  storage outside the checkout. Keep them off uploaded artifacts: they are unsanitized.
+
+## 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.

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

@@ -0,0 +1,164 @@
+# Android foundation: shell snippets
+
+Replace each `<placeholder>` with the repo's real value. Tool shells do not keep variables,
+functions or traps between calls: step 1 writes `.cache/android-env.sh`, which also `cd`s
+into the worktree, and every later block starts by sourcing it by absolute path, and steps 6–8 run as one command through the bundled
+`scripts/device-run.sh`.
+
+## 1. Checkout and environment
+
+```bash
+set -euo pipefail
+git fetch origin main
+git worktree add -b <new-branch> ../<repo>-android-setup origin/main
+cd ../<repo>-android-setup
+git rev-parse HEAD
+mkdir -p .cache
+{ echo 'set -euo pipefail'; printf 'cd %q\n' "$PWD"; } > .cache/android-env.sh
+cat >> .cache/android-env.sh <<'ENV'
+
+# Repo-specific names, read from the repo's journey wrapper and device harness.
+export APP_FILTER=<android-workspace-package>         # pnpm --filter target
+export DEVICE_PYTHON_DIR=<venv-dir-the-wrapper-reads> # e.g. the default in the wrapper
+export DB_NAME_PREFIX=<db-prefix-the-harness-accepts> # the harness rejects other names
+export DB_URL_VAR=<harness-admin-url-variable>        # e.g. SHARD_ADMIN_URL
+export DB_NAME_VAR=<harness-db-name-variable>         # e.g. SHARD_DB_NAME
+
+# Host paths. Example values are for Apple Silicon with Android Studio.
+export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
+export ANDROID_HOME="$HOME/Library/Android/sdk"
+export ANDROID_SDK_ROOT="$ANDROID_HOME"
+export SOURCE_AVD="$HOME/.android/avd/<installed-avd>.avd"
+export SEED_GRADLE_HOME="$HOME/.gradle"
+export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$PATH"
+
+# Private caches.
+export GRADLE_USER_HOME="$PWD/.cache/gradle"
+export ANDROID_USER_HOME="$PWD/.cache/android-user"
+export ANDROID_AVD_HOME="$PWD/.cache/android-avd"
+export TMPDIR="$PWD/.cache/tmp"
+export npm_config_cache="$PWD/.cache/npm"
+export npm_config_devdir="$PWD/.cache/node-gyp"
+export PNPM_CONFIG_STORE_DIR="$PWD/.cache/pnpm-store"
+export PNPM_CONFIG_CACHE_DIR="$PWD/.cache/pnpm"
+case "${JAVA_TOOL_OPTIONS:-}" in *java.io.tmpdir*) ;; *)
+  export JAVA_TOOL_OPTIONS="${JAVA_TOOL_OPTIONS:+$JAVA_TOOL_OPTIONS }-Djava.io.tmpdir=$TMPDIR" ;; esac
+
+# Run identifiers: an even console port in 5554-5584 (adb scans only that range),
+# and backend/Metro ports under the names the journey wrapper reads.
+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>
+ENV
+source .cache/android-env.sh
+mkdir -p "$TMPDIR" "$npm_config_cache" "$npm_config_devdir" \
+  "$ANDROID_USER_HOME" "$ANDROID_AVD_HOME" .cache/logs
+
+node --version; pnpm --version; java -version; python3 --version
+adb version; "$ANDROID_HOME/emulator/emulator" -version
+# Versions come from the repo's native config and CI preflight.
+for component in platforms/android-<api> build-tools/<build-tools> ndk/<ndk> cmake/<cmake>; do
+  test -d "$ANDROID_HOME/$component" || { echo "Missing SDK: $component" >&2; exit 1; }
+done
+```
+
+If the wrapper reads its port or Python variables under other names, export those names in
+`android-env.sh` instead.
+
+## 2. Install and check
+
+```bash
+source <worktree>/.cache/android-env.sh
+pnpm install --frozen-lockfile --store-dir "$PWD/.cache/pnpm-store"
+pnpm --filter "$APP_FILTER" test
+pnpm --filter "$APP_FILTER" typecheck
+EXPO_PUBLIC_API_URL=https://app.invalid \
+  pnpm --filter "$APP_FILTER" exec expo export --platform android
+python3 -m venv "$DEVICE_PYTHON_DIR"
+"$DEVICE_PYTHON_DIR/bin/python3" -m pip install uiautomator2==<harness-pinned-version>
+```
+
+## 3. Gradle dependencies (pick one)
+
+Seed from a trusted Gradle home:
+
+```bash
+source <worktree>/.cache/android-env.sh
+mkdir -p "$GRADLE_USER_HOME/caches/modules-2/files-2.1"
+rsync -r --ignore-existing \
+  --exclude='*.lock' --exclude='*.lck' --exclude='*.tmp' \
+  "$SEED_GRADLE_HOME/caches/modules-2/files-2.1/" \
+  "$GRADLE_USER_HOME/caches/modules-2/files-2.1/"
+```
+
+Or wire a trusted Maven proxy into the private Gradle home. Append the exports to
+`android-env.sh` so the build in step 4 sees them. Route every repository the build uses,
+JitPack included; a route left unset goes straight upstream.
+
+```bash
+source <worktree>/.cache/android-env.sh
+cat >> "$PWD/.cache/android-env.sh" <<'ENV'
+export GRADLE_MAVEN_REPOSITORY=<proxy>/maven/
+export GRADLE_GOOGLE_REPOSITORY=<proxy>/google-maven/
+export GRADLE_PLUGIN_REPOSITORY=<proxy>/gradle-plugins/
+export GRADLE_JITPACK_REPOSITORY=<proxy>/jitpack/
+ENV
+curl --fail --silent --show-error --max-time 10 <proxy-health-url>
+install -d "$GRADLE_USER_HOME/init.d"
+install -m 0644 <path/to/proxy.init.gradle> "$GRADLE_USER_HOME/init.d/proxy.init.gradle"
+```
+
+## 4. Build
+
+```bash
+source <worktree>/.cache/android-env.sh
+pnpm build:android --max-workers=2 -Dorg.gradle.parallel=false \
+  -Pandroid.builder.sdkDownload=false --console=plain --info \
+  2>&1 | tee .cache/logs/gradle.log
+APK=<path/to/app/build/outputs/apk/debug/app-debug.apk>
+shasum -a 256 "$APK"            # sha256sum on Linux
+unzip -l "$APK" | grep -E 'lib/[^/]+/libreactnative\.so'
+```
+
+## 5. Owned emulator
+
+```bash
+source <worktree>/.cache/android-env.sh
+test -f "$SOURCE_AVD/config.ini"
+test ! -e "$ANDROID_AVD_HOME/$SETUP_AVD.ini"
+test ! -e "$ANDROID_AVD_HOME/$SETUP_AVD.avd"
+grep '^image.sysdir.1' "$SOURCE_AVD/config.ini"   # must be an installed, host-compatible image
+mkdir "$ANDROID_AVD_HOME/$SETUP_AVD.avd"
+# Copy without the source's RAM size and give the guest 4 GB (gotchas: adb transport drops).
+grep -Ev '^hw\.ramSize[[:space:]]*=' "$SOURCE_AVD/config.ini" > "$ANDROID_AVD_HOME/$SETUP_AVD.avd/config.ini"
+echo 'hw.ramSize=4096' >> "$ANDROID_AVD_HOME/$SETUP_AVD.avd/config.ini"
+printf 'avd.ini.encoding=UTF-8\npath=%s\ntarget=android-<api>\n' \
+  "$ANDROID_AVD_HOME/$SETUP_AVD.avd" > "$ANDROID_AVD_HOME/$SETUP_AVD.ini"
+```
+
+## 6–8. Cleanup, resources and journey: one command
+
+```bash
+source <worktree>/.cache/android-env.sh
+bash <skill-base-dir>/scripts/device-run.sh \
+  --drop node <path/to/device-harness.mjs> drop \
+  -- bash <path/to/foundation-journey-wrapper.sh>
+```
+
+Pass each command as separate words, not as one quoted string. The script:
+
+1. Registers the cleanup trap before anything starts.
+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.
+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.

package/skills/app-dev/android-foundation/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

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

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# Boot an owned emulator and a disposable PostgreSQL, run the device journey, and
+# clean up only what this run started. Run it as ONE command: an agent's tool
+# shell does not keep variables, functions or traps between calls.
+#
+# Usage:
+#   device-run.sh --drop <db-drop command...> -- <journey command...>
+#
+# Required environment:
+#   ANDROID_HOME           SDK root (emulator/emulator)
+#   SETUP_AVD              private AVD name under $ANDROID_AVD_HOME
+#   EMULATOR_PORT          even console port, 5554-5584 (adb scans only this range)
+#   ANDROID_BACKEND_PORT   backend port the journey uses
+#   ANDROID_METRO_PORT     Metro port the journey uses
+#   DB_NAME_PREFIX         database-name prefix the harness accepts, e.g. app_e2e_
+# Optional environment:
+#   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)
+#
+# Exports ANDROID_EMULATOR_SERIAL, $DB_URL_VAR and $DB_NAME_VAR to both commands.
+# Prints `original_stage_exit=<n> cleanup_exit=<n>` last and exits with the
+# stage's status when it failed, else the cleanup status.
+set -euo pipefail
+
+drop_cmd=()
+journey_cmd=()
+if test "${1:-}" != --drop; then
+  echo "usage: device-run.sh --drop <cmd...> -- <journey cmd...>" >&2
+  exit 2
+fi
+shift
+while test $# -gt 0 && test "$1" != --; do drop_cmd+=("$1"); shift; done
+if test $# -eq 0; then echo "missing -- before the journey command" >&2; exit 2; fi
+shift
+journey_cmd=("$@")
+if test ${#drop_cmd[@]} -eq 0 || test ${#journey_cmd[@]} -eq 0; then
+  echo "both the drop command and the journey command are required" >&2
+  exit 2
+fi
+
+: "${ANDROID_HOME:?}" "${SETUP_AVD:?}" "${EMULATOR_PORT:?}"
+: "${ANDROID_BACKEND_PORT:?}" "${ANDROID_METRO_PORT:?}" "${DB_NAME_PREFIX:?}"
+POSTGRES_IMAGE="${POSTGRES_IMAGE:-postgres:17}"
+DB_URL_VAR="${DB_URL_VAR:-SHARD_ADMIN_URL}"
+DB_NAME_VAR="${DB_NAME_VAR:-SHARD_DB_NAME}"
+LOG_DIR="${LOG_DIR:-.cache/logs}"
+BOUNDED_SECONDS="${BOUNDED_SECONDS:-30}"
+BOOT_ATTEMPTS="${BOOT_ATTEMPTS:-60}"
+KILL_GRACE_SECONDS="${KILL_GRACE_SECONDS:-10}"
+
+if ! [[ "$EMULATOR_PORT" =~ ^[0-9]+$ ]] || (( EMULATOR_PORT < 5554 || EMULATOR_PORT > 5584 || EMULATOR_PORT % 2 )); then
+  echo "EMULATOR_PORT must be an even port in 5554-5584: $EMULATOR_PORT" >&2
+  exit 2
+fi
+
+mkdir -p "$LOG_DIR"
+run_dir="$(mktemp -d "${TMPDIR:-/tmp}/android-device-run.XXXXXX")"
+emulator_pid=""
+db_ready=""
+export ANDROID_EMULATOR_SERIAL="emulator-$EMULATOR_PORT"
+
+bounded() {
+  # Kill the whole process group on timeout: a surviving grandchild would hold
+  # the output pipe open and stall the caller past the deadline.
+  python3 -c 'import os, signal, subprocess, sys
+limit = float(sys.argv[1])
+child = subprocess.Popen(sys.argv[2:], start_new_session=True)
+try:
+    sys.exit(child.wait(timeout=limit))
+except subprocess.TimeoutExpired:
+    os.killpg(child.pid, signal.SIGKILL)
+    child.wait()
+    print("Command exceeded %s seconds: %s" % (sys.argv[1], " ".join(sys.argv[2:])), file=sys.stderr)
+    sys.exit(124)' "$BOUNDED_SECONDS" "$@"
+}
+
+cleanup() {
+  original_status=$?
+  trap - EXIT INT TERM
+  set +e
+  cleanup_status=0
+  if test -n "$db_ready"; then
+    bounded "${drop_cmd[@]}" || cleanup_status=1
+  fi
+  if test -n "$emulator_pid"; then
+    if kill -0 "$emulator_pid" 2>/dev/null; then
+      kill -TERM "$emulator_pid" || cleanup_status=1
+    fi
+    for _ in $(seq 1 "$KILL_GRACE_SECONDS"); do
+      kill -0 "$emulator_pid" 2>/dev/null || break
+      sleep 1
+    done
+    if kill -0 "$emulator_pid" 2>/dev/null; then
+      cleanup_status=1
+      kill -KILL "$emulator_pid"
+      sleep 1
+    fi
+    if kill -0 "$emulator_pid" 2>/dev/null; then
+      cleanup_status=1
+    else
+      wait "$emulator_pid"
+      emulator_status=$?
+      # 0 = clean exit; 143 = ended by our TERM. A KILL was already counted above.
+      case "$emulator_status" in 0|143) ;; *) cleanup_status=1 ;; esac
+    fi
+  fi
+  if test -s "$run_dir/postgres.cid"; then
+    container_id="$(< "$run_dir/postgres.cid")"
+    bounded docker rm --force "$container_id" >/dev/null || cleanup_status=1
+    remaining="$(bounded docker ps -a --no-trunc --filter "id=$container_id" --format '{{.ID}}')" || cleanup_status=1
+    test -z "$remaining" || cleanup_status=1
+  fi
+  printf 'original_stage_exit=%s cleanup_exit=%s\n' "$original_status" "$cleanup_status"
+  if test "$original_status" -ne 0; then exit "$original_status"; fi
+  exit "$cleanup_status"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+# Every port this run listens on or dials must be free before anything starts.
+python3 -c 'import socket, sys
+for port in map(int, sys.argv[1:]):
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", port))' \
+  "$EMULATOR_PORT" "$((EMULATOR_PORT + 1))" "$ANDROID_BACKEND_PORT" "$ANDROID_METRO_PORT"
+
+# Start the ADB server first so the emulator registers with it on boot.
+bounded adb start-server
+
+# -memory 4096 overrides the AVD's hw.ramSize, so a reused 2 GB AVD cannot starve the
+# guest kernel's vsock allocations and drop adb mid-journey (references/gotchas.md).
+"$ANDROID_HOME/emulator/emulator" -avd "$SETUP_AVD" -port "$EMULATOR_PORT" -memory 4096 \
+  -no-window -no-audio -no-snapshot -gpu swiftshader_indirect -accel on \
+  > "$LOG_DIR/emulator.log" 2>&1 &
+emulator_pid=$!
+
+container_name="android-device-run-$(date +%s)-$$"
+bounded docker run --detach --name "$container_name" --cidfile "$run_dir/postgres.cid" \
+  --publish 127.0.0.1::5432 --env POSTGRES_USER=postgres \
+  --env POSTGRES_PASSWORD=postgres --env POSTGRES_DB=postgres "$POSTGRES_IMAGE" >/dev/null
+db_port="$(bounded docker port "$container_name" 5432/tcp | head -1 | awk -F: '{print $NF}')"
+test -n "$db_port"
+
+boot_state=""
+for _ in $(seq 1 "$BOOT_ATTEMPTS"); do
+  if boot_state="$(bounded adb -s "$ANDROID_EMULATOR_SERIAL" shell getprop sys.boot_completed 2>/dev/null | tr -d '\r')"; then
+    if test "$boot_state" = 1; then break; fi
+  else
+    probe_status=$?
+    # A stalled command is terminal, not "not ready yet".
+    if test "$probe_status" -eq 124; then exit 124; fi
+  fi
+  sleep 2
+done
+if test "$boot_state" != 1; then echo "emulator did not finish booting" >&2; exit 1; fi
+
+pg_ready=""
+for _ in $(seq 1 30); do
+  if bounded docker exec "$container_name" pg_isready -U postgres >/dev/null; then
+    pg_ready=1
+    break
+  else
+    probe_status=$?
+    if test "$probe_status" -eq 124; then exit 124; fi
+  fi
+  sleep 1
+done
+if test -z "$pg_ready"; then echo "PostgreSQL did not become ready" >&2; exit 1; fi
+
+# The password belongs only to this disposable loopback container.
+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_cmd[@]}"