@1aboveio/skills 1.0.13 → 1.0.15

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

@@ -0,0 +1,389 @@
+# Android setup and device execution
+
+Read [setup rules](#setup-rules) and [owned-resource cleanup](#owned-resource-cleanup)
+before these commands. All stages are for fresh setup proof; established workspaces use
+the [validation ladder](../SKILL.md#validation-ladder) and the
+[owned development session](#owned-development-session), and rerun only invalidated stages.
+
+Treat the shell blocks as an Expo/pnpm/UiAutomator example, not a required stack. Use the
+repo's verified package manager, native build, bundle/export step and existing test harness.
+Keep ownership, installed-toolchain, deadlines, cleanup and proof requirements mandatory;
+do not install Expo, Python automation or a new harness to make another RN project fit.
+
+Replace each `<placeholder>` with the repo's real value. Tool shells do not keep variables,
+functions or traps between calls: step 1 resolves the workspace and writes
+`.cache/android-env.sh`, which also `cd`s into it; 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`.
+
+## Contents
+
+- [Fresh setup stages](#1-workspace-and-environment)
+- [Owned development session](#owned-development-session)
+- [Scoped ABI selection](#scoped-abi-selection)
+- [Setup rules](#setup-rules)
+- [Owned-resource cleanup](#owned-resource-cleanup)
+- [Setup evidence](#evidence-record)
+
+## 1. Workspace and environment
+
+Workspace precedence is owned by [workspace.md](workspace.md). Do not create a worktree,
+switch branch, fetch or reset when the caller supplied an isolated workspace.
+
+```bash
+set -euo pipefail
+ASSIGNED_WORKSPACE=<assigned-workspace-or-empty>
+CANDIDATE_HEAD=<candidate-head-or-empty>
+WORKSPACE="${ASSIGNED_WORKSPACE:?use the caller assignment or native-start result from workspace.md}"
+test -d "$WORKSPACE"
+git -C "$WORKSPACE" rev-parse --is-inside-work-tree >/dev/null
+cd "$WORKSPACE"
+actual_head="$(git rev-parse HEAD)"
+test -z "$CANDIDATE_HEAD" || test "$actual_head" = "$(git rev-parse "$CANDIDATE_HEAD^{commit}")" || {
+  echo "workspace HEAD $actual_head != candidate $CANDIDATE_HEAD; report it; do not switch" >&2
+  exit 1
+}
+mkdir -p .cache
+{ echo 'set -euo pipefail'; printf 'cd %q\n' "$PWD"; printf 'export ANDROID_SOURCE_HEAD=%q\n' "$actual_head"; } > .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>
+# 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" \
+  "$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
+```
+
+The recorded standalone path is reused on retries; verify its lifecycle record names this
+run, branch and base. If an assigned path is missing, is not a Git worktree, or is at another
+revision, stop and report instead of creating another checkout. Never fall back to
+`../<repo>-android-setup`.
+
+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
+
+Run the repo's frozen install, relevant tests and typecheck. Export/bundle using the
+selected framework's supported command; use `expo export` only for an Expo project.
+Create a Python venv and pin UiAutomator only when the existing harness uses them.
+For Yarn/npm or an instrumentation-only harness, substitute its verified commands and
+omit unused pnpm/Python environment settings; do not invent replacements or install tools.
+
+```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.
+
+If the opted-in proxy fails, stop and fix its routing; never fall back to direct
+downloads or disable TLS checks. The proxy covers Maven repositories only. Route the
+Gradle wrapper ZIP and pnpm as the repo's `CONTRIBUTING.md` requires. Without a seed or
+opted-in proxy, use upstream intentionally and allow for a cold build.
+
+```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
+
+Copy only `config.ini`, never user data or snapshots. Verify that `image.sysdir.1` is an
+installed, host-compatible system image and that `target` matches it. Give the guest
+4 GB to avoid mid-journey ADB drops. A hand-written config needs the hardware keys in
+[gotchas](gotchas.md#a-hand-written-avd-misses-the-screen).
+
+```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`. 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 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.
+
+Expect every selected scenario's `PASS` marker, screenshots, and backend and Metro logs
+when the selected variant uses those services. Preserve the failed checkpoint's evidence
+before cleanup. A release build with embedded assets does not require Metro by default.
+
+## Owned development session
+
+Apply the safety/proof requirements above to a new environment or invalidated setup
+assumptions, using only the repo's applicable stages and verified tools. The example
+commands are not universal requirements or a per-incremental-build checklist. Ordinary iteration runs against the
+owned development session described in [workspace.md](workspace.md): one development emulator
+and ADB endpoint, Metro, one compatible Gradle daemon on the private `GRADLE_USER_HOME`, and
+the workspace's build outputs. Rerun only the stages whose inputs changed, and end the session
+or hand it off before finishing.
+
+Keep that fast path fast:
+
+- Reuse the compatible Gradle daemon and private outputs where repo policy permits. CI or
+  one-shot verification may require `--no-daemon`; do not copy it automatically into a
+  local fast path, change global daemon settings or use shared writable caches. Preserve
+  the actual host/slot capacity limits and repo JVM constraints in every lane.
+- Add no configuration-cache, parallel, worker or JVM tuning without a measured need. Keep
+  the repo's JVM and resource-capacity settings, and keep this recipe's own flags as written.
+- A tracked native project that already builds and installs needs no routine `expo prebuild`
+  or `clean`, and no dependency reinstall.
+- Do not rerun the disposable stack from stages 5–8 for an edit. Reuse the existing
+  development owner. At L2/L3, follow the gate's fresh-state requirements; an authorized
+  fresh install on an existing owned emulator need not boot another guest if data isolation
+  is sufficient. The generic runner is not a second owner for an existing session.
+- Verify every Gradle task name against the actual task graph before using it. `assembleDebug`
+  and `installDebug` may also package instrumentation or test APKs, so do not treat either as
+  app-only proof without checking the packaged artifacts.
+
+### Scoped ABI selection
+
+Focused L1 work may build only the ABI of the owned device, where repo policy permits. Ask
+the device instead of guessing, and name its serial so both commands respect the caller's ADB
+endpoint. Give the probe a 30-second command deadline through the existing owner; do not
+wait indefinitely on a lost transport:
+
+```bash
+source <worktree>/.cache/android-env.sh
+adb -s <owned-serial> shell getprop ro.product.cpu.abi | tr -d '\r'
+# The ABIs the native build configures, e.g. the reactNativeArchitectures values.
+grep -n 'reactNativeArchitectures' <native-gradle-properties-file>
+```
+
+The printed ABI must appear in that configured list; stop and report any other value. Then
+scope one command to it, through the same build entry point as step 4, which forwards Gradle
+arguments. Tool shells do not keep variables between calls, so restate the verified value:
+
+```bash
+source <worktree>/.cache/android-env.sh
+DEVICE_ABI=<verified-abi-from-the-previous-command>
+pnpm <repo-build-entry> -PreactNativeArchitectures="$DEVICE_ABI" \
+  -Pandroid.builder.sdkDownload=false
+```
+
+Verify that this entry point forwards both properties, and retain the repo's applicable
+capacity and build-safety flags. Flags from an earlier command are not inherited.
+
+Do not change the shared checked-in ABI defaults, persist the flag in `gradle.properties`, or
+hardcode `x86` or `x86_64`, and keep the every-configured-ABI build as setup proof and release
+acceptance. An emulator-ABI build proves only that ABI.
+
+## Setup rules
+
+- Resolve the workspace first; [workspace.md](workspace.md) owns
+  precedence: an assigned isolated workspace and candidate HEAD win, feature work, fixes and
+  diagnosis reuse the owned workspace, and standalone setup creates one managed workspace
+  only with no usable assignment. Read its actual HEAD; never substitute `origin/main`, a new
+  branch or another checkout, 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. 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,
+  platform-tools, emulator, system image) is already installed. If one is missing, stop and
+  provision it separately. Never upgrade or install into a shared SDK during a journey;
+  build with `-Pandroid.builder.sdkDownload=false`.
+- Install with `--frozen-lockfile`. Do not routinely run `clean`, reinstall dependencies or
+  run `expo prebuild`. The native project is tracked, and prebuild needs a reviewed native
+  change.
+- Build every configured ABI for setup proof and release acceptance. An emulator-only
+  APK proves only that ABI. L1 focused native validation may use the emulator ABI where
+  repo policy permits, discovered from the owned device as in
+  [scoped ABI selection](#scoped-abi-selection); retain additional checks for affected ABI
+  configuration and all required native/ABI CI gates. Do not claim all-ABI proof from one
+  incremental build.
+- 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.
+
+Ordinary edits reuse the [owned development session](#owned-development-session) instead of
+repeating these stages. Every stop still follows the cleanup rules below.
+
+## Owned-resource cleanup
+
+- Clean up only what this run started: the emulator child PID, the container ID from the
+  CID file, and the named database; these are short-lived, unlike the development workspace
+  and its private caches. 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.
+- The development runtime ends with the session, not after each check. Use its existing
+  owner's bounded shutdown, distinguishing supervised children/process groups from
+  persistent daemons. Shell `wait` and child exit codes apply only to children of that
+  shell; do not use them to attest termination of an adopted service or Gradle daemon.
+  The build client's exit does not mean its daemon exited. Record the daemon's own
+  identity and private Gradle home/version, not merely the client PID.
+- For a supervised runtime, stop through its harness owner and verify the owned group
+  and descendants exited; a Metro wrapper exiting alone is insufficient. For Gradle or
+  another daemon, use the verified owner-specific stop with the recorded private home,
+  version and endpoint, then verify the original process identity is gone and owned
+  endpoints are released where applicable. Never use a shared/global daemon stop,
+  `adb kill-server` or a broad kill. If scope or exit cannot be verified, report the
+  retained resource and cleanup gap or arrange explicit handoff; do not signal a guessed
+  PID or report success. Preserve the bounded-stop and failure-reporting rules below.
+- 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 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.
+- Record existing working changes before tools run. If Expo rewrites `android/tsconfig.json`
+  or deletes `android/expo-env.d.ts`, remove only unwanted changes attributable to that tool
+  execution. Preserve pre-existing and intentional task edits. If attribution is unclear,
+  retain the files and report the conflict; do not restore a whole file merely because
+  Expo touched it.
+
+## Evidence record
+
+For setup proof only. Record:
+
+- Source SHA and the workspace root/path/base/branch/owner from the lifecycle record; host OS
+  and architecture, the Expo SDK, and the node, pnpm, JDK, Python and emulator versions.
+- System image API, image type and ABI. The AVD name, serial and ports are run
+  identifiers, not shared resources.
+- Each stage's exit status and duration.
+- The APK's SHA-256 (`shasum -a 256` or `sha256sum`) and its per-ABI `lib/` entries
+  (`unzip -l`), checked on the APK itself rather than inferred from Gradle flags.
+- The journey's `PASS` markers and the cleanup results: database dropped, emulator exited,
+  container removed, no listeners left on the backend or Metro ports.
+- Earlier failed or incomplete attempts. A later pass does not erase them.
+
+State what the run does not prove: tablet, accessibility (TalkBack), physical devices,
+signing, distribution, and any feature acceptance beyond the journey. Publish only
+sanitized evidence: no authentication codes, session cookies, customer data or raw
+payment payloads.

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

@@ -0,0 +1,156 @@
+# Android workspace lifecycle
+
+The coordinator or caller owns workspace selection. Resolve it once, before any setup stage,
+and record the result. This reference owns workspace and runtime ownership: which resources
+this run owns, which of them persist across attempts and which are per-run. Cache layout, SDK
+isolation and the concrete stop commands stay in [setup.md](setup.md),
+[Owned development session](setup.md#owned-development-session) and
+[Owned-resource cleanup](setup.md#owned-resource-cleanup).
+
+## Precedence
+
+1. **Assigned workspace and candidate HEAD.** When the caller supplies an isolated workspace
+   and a candidate HEAD, use that workspace and that revision. Do not create a worktree or
+   branch, fetch, reset or switch revisions. Read `git rev-parse HEAD` and report it as the
+   source SHA. If it differs from the candidate HEAD, stop and report the mismatch; never
+   switch the workspace to match.
+2. **Existing owned workspace.** Feature work, fixes and diagnosis reuse the workspace this
+   run or unit already owns, with its private caches, venv and AVD profile. Do not make a
+   second workspace for a retry, a correction or a read-only investigation.
+3. **Standalone fresh setup.** Only when the coordinator reports no usable assignment. Create
+   one managed workspace at
+   `<repo>/.resolve-issues/rush/<run-id>/units/native`. Never create a sibling checkout such
+   as `../<repo>-android-setup`, and never add a second managed path for a retry.
+
+Android and iOS setup in the same run share that one managed workspace; their private cache
+subdirectories and short-lived processes stay separate.
+
+An assigned path that is missing, is not a Git worktree, or is at another revision is not an
+invitation to substitute a fresh checkout: stop and report it. For diagnosis, name the actual
+checkout and HEAD and confirm it contains the failing code; the repository root or another
+checkout may lag the candidate.
+
+## Record before creating
+
+The bundled `scripts/workspace-runtime` is generated from the shared lifecycle
+engine and ships with this skill. Only for standalone fresh setup, run:
+
+```bash
+node <skill-base-dir>/scripts/workspace-runtime/bin/workspaces.mjs native-start --repo <canonical-root> \
+  --platform android --target <verified-target-branch> --base <candidate-SHA> --json
+```
+
+The command records root, owner, exact base, branch, workspace and disposable cache
+paths before creating anything. Use its returned `workspace` as `ASSIGNED_WORKSPACE`
+and `sourceSha` as `CANDIDATE_HEAD` in setup. Keep `run` and `runId`; repeat with
+`--run-id <returned-run-id>` and the same base, target and kind for retries. Never
+invoke it inside a coordinator-assigned unit. It never substitutes `origin/main`
+for the requested source or resets an existing workspace.
+For a package below the root, pass `--native-dir <package-root-containing-android>`.
+Declare other installs or build directories before use with repeated
+`--disposable <exact-workspace-relative-path>`, including package-local `node_modules`.
+
+## Development workspace, owned session runtime and disposable runs
+
+The workspace, its private caches under `.cache/`, its venv and its AVD profile are
+development resources: retain them across retries and fixes, and keep them private to this
+workspace. Never relocate them to a global cache or share them with a concurrent owner.
+
+The owned **development session** has one lifecycle per owner. Start it once, record its PID
+identity, serial, ports and log paths, and reuse it across every edit, fix and check attempt
+in the session:
+
+- the development emulator and the ADB endpoint it publishes, addressed by its owned serial;
+- Metro, or the repo's development server, on its recorded port;
+- one compatible Gradle daemon on the workspace's private `GRADLE_USER_HOME`, honoring the
+  repo's JVM and resource-capacity settings;
+- the build outputs and installed app state under the workspace.
+
+Within one session, do not start a second emulator, Metro, daemon or cache home because
+the running one is inconvenient: keep the existing owner, do not create a second lifecycle,
+and do not accumulate abandoned services. Long-lived processes stay under the harness's own
+tracking so their exit is observable. Never `nohup`, `setsid` or `disown` a service into a
+state this run cannot signal, and never leave one with no owner at all.
+
+**Disposable acceptance and integration resources** follow their checkpoint's contract.
+The `device-run.sh` emulator child, PostgreSQL container and named database exist for one
+journey and are stopped by that run under [cleanup](setup.md#owned-resource-cleanup).
+Do not start that stack for every edit. A fresh install does not automatically require a
+new AVD or reboot: an existing owned emulator may be used when the gate permits it and
+disposable app/test data can be isolated without destroying development state. Do not
+inherit development authentication/database state as proof, or clear a borrowed device.
+
+A session ends when the assignment ends, not when one check passes. Stop the services this
+run started and confirm their exit under the existing cleanup rules, or hand off the ones
+still running with their owner, PID identity, serial, ports, log paths and how to stop them.
+A passing check, a reported result or a review handoff is not a session end.
+The stop must match the resource: use the harness owner for supervised groups and a
+verified private stop for daemons; do not shell-wait a nonchild or treat a wrapper's exit
+as proof that its descendants stopped. Record uncertain cleanup as retained, not success.
+
+Fast feedback comes from reuse, not from a fresh environment per attempt:
+
+- Go incremental: one bounded edit/check cycle, reading the previous result before the next.
+  Build only when changed native or packaged inputs require it; refreshable JS needs no build.
+- Do not recreate state for a clean start: no second emulator boot, Metro restart, `adb
+  kill-server`, fresh Gradle daemon, `clean`, dependency reinstall or `expo prebuild` of a
+  tracked native project for an ordinary fix.
+- Prefer the cheapest check that proves the change (focused test, relevant typecheck, an app
+  that is already running) before scheduling the disposable device stack.
+- Add no new pool, lease manager, snapshot-default AVD, provisioning script or second
+  launcher to make reuse work; the existing owner, launcher and cleanup rules are the
+  mechanism.
+
+A read-only diagnosis does not require a clean environment. Reuse the owned workspace, its
+caches and the session this run still owns; create only the services the observation needs,
+and preserve the failed environment's evidence. Do not rebuild, reinstall or re-provision
+merely because the failure is being investigated.
+
+## Parallel development sessions
+
+Assign warm servers by independently changing source/configuration, not by agent count.
+Keep each session warm between its own checks:
+
+| Work arrangement | Runtime rule |
+| --- | --- |
+| Independent worktrees, branches or runtime configurations | Use separate Metro instances rooted in their actual workspaces, unique host ports and explicit device mappings. Keep writable caches, build outputs and test data private. |
+| Several readers or intentionally integrated checks on the same source/configuration | Reuse one server under a designated owner. Coordinate edits and check snapshots; record that results cover the combined working state, not isolated candidates. |
+| Limited device/host capacity | Run ready host checks concurrently and schedule conflicting device checks through the existing owner. Do not start excess emulators or create a new pool/lease system. |
+
+For example, one emulator may map its device port 8081 to session A's private host port,
+while a different emulator maps its device port 8081 to session B's private host port.
+The host ports must differ; the device-local ports need not. Use the caller-selected ADB
+endpoint and exact owned serial. Verify the app's actual bundle source, not only `/status`.
+
+Do not point one Metro at alternating candidate trees or mutate another session's reverse
+mapping, installed app or database. Keep device state exclusive during mutating checks.
+If one device must serve different candidates sequentially, end the previous check and
+let its owner explicitly reassign/reconfigure it and verify the new app/source mapping;
+do not silently switch it while a test is running. Sharing a server does not make concurrent
+writes to the same source tree independent or protect tests from mid-run source changes.
+
+Do not assume a shared backend is safe for fixtures: share only when its isolation and
+ownership contract explicitly permit it; otherwise keep candidate test data separate.
+Stop shared services only through their owner after all users release them, or explicitly
+hand them off. Do not kill a shared server because one agent finished its task.
+
+## Completion
+
+At the end of the assignment, return the workspace, its cache paths and any retained process
+records to the coordinator for final cleanup. The coordinator owns deletion and retention.
+Register the path with the run's cleanup owner so final cleanup can tell a delivered
+standalone run from unfinished or unpublished work.
+
+- A successful, delivered standalone run must not retain an unbounded cache: mark the
+  workspace and its disposable caches for final cleanup. After stopping its owned
+  services, run `node <skill-base-dir>/scripts/workspace-runtime/bin/workspaces.mjs native-finish --run <run> --json`
+  from the owner checkout. This uses the same cleanup engine as issue workflows.
+- Unfinished or unpublished standalone work keeps the workspace and caches for the next
+  attempt; report what is retained and why.
+
+The parent lifecycle record is authoritative for ownership, retention and final cleanup.
+Before `native-finish`, record the session's end: either the services this run started were
+stopped and their exit confirmed, or the ones still running were handed off explicitly as
+described above.
+An explicit handoff does not authorize removing a workspace or cache still used by the
+receiving owner. Retain it until ownership and delivery cleanup checks permit removal.