Merge pull request 'Android: install and launch the package the APK declares' (#163) from fix/159-android-task-app-id into main

android-tier.md carried a warning block telling the reader not to use
run:device or deploy-device, and offered a manual sequence instead.
Both are wrong now: the tasks are the way in, and the warning would
read as a live hazard. It becomes a note about what changed, and the
manual sequence stays as the smallest thing that works when you want no
script between you and adb.

"The identity is declared twice" was the section this file had carried
for five phases saying nothing enforced that the two ids agree. It
describes the enforcement now, plus what APP_ID means since it stopped
being a setting it never was.

NOTES.md takes the four measurements: that the uninstall existed only
to cover a missing -r (which is what makes deleting it a fix rather
than a trade), that the emulator tasks installed on a phone, what
reading the id back costs, and the boot-wait race filed as #162.

.pi/skills/yellowjacket-dev/references/android-tier.md

@@ -194,9 +194,13 @@ like the app's fault and none is:
 |---|---|---|
 | x86_64 | modernc's raw `lstat` vs seccomp | SIGSYS, syscall 6 |
 | arm64, translated | Go reads `ID_AA64ISAR0_EL1` | SIGILL |
-| arm64, real device | — | unverified, still |
+| arm64, real device | **runs** (2026-08-20) | — |
 
-**A physical arm64 device remains the only verification path.**
+**A physical arm64 device remains the only verification path**, and it
+has now been walked: a Light Phone III (TLP301, Android 14 / SDK 34,
+arm64-v8a, WebView Chrome 113 at 424x439). The app builds, installs,
+launches and stays up; `make android-smoke SECONDS=60` passes on it.
+What that run *found* is the lifecycle fault below.
 
 ### What was fixed to get here
 
@@ -210,6 +214,11 @@ no-op. `backend/system` gained no import of the Wails application
 package, which matters for the same reason `backend/events` is split by
 the `indexbuild` tag.
 
+**And `main()` is now latched to one run per process** (#52). That is
+the second `os.Exit(1)` in this file's history and it had the same
+signature as the first, which is the argument for #160: both were named
+exactly by an `slog` line that went to `/dev/null`.
+
 ### What is still not done
 
 The shell is still a desktop shell, and the x86_64 half of the APK is
@@ -249,10 +258,25 @@ one.
 `build/android/Taskfile.yml` ships more than the Makefile wraps, and
 they are the right thing to reach for when you want something one-off:
 
+> **These four were unsafe until #159 and are now the way in.** All of
+> them began with `adb uninstall {{.APP_ID}}`, where `APP_ID` defaulted
+> to `app.yellowjacket` — the **release** id — while `run` and
+> `run:device` build the **debug** variant, whose id is
+> `app.yellowjacket.dev`. So they uninstalled the user's app, taking
+> the library with it, installed a different package, and then failed
+> to launch the one they had removed.
+>
+> They share `scripts/android-deploy.sh` now, which **never**
+> uninstalls (`install -r`, and a changed signing certificate is
+> reported with the command rather than acted on), reads the package id
+> back out of the built APK, and refuses a target that is not the kind
+> the task names. There is nothing left to avoid; the manual sequence
+> below is kept because it is still the smallest thing that works.
+
 ```
 wails3 task android:run              # debug build + emulator install + launch
-wails3 task android:run:device       # same, first connected physical device
-wails3 task android:deploy-device    # production APK to a device
+wails3 task android:run:device       # debug build + install + launch on a phone
+wails3 task android:deploy-device    # release build, same
 wails3 task android:bundle:fat       # AAB, for a Play Store upload
 wails3 task android:studio           # open build/android/ in Android Studio
 wails3 task android:device:list
@@ -260,6 +284,16 @@ wails3 task android:logs:all
 wails3 task android:clean
 ```
 
+**`run` and `deploy-emulator` mean the emulator, and now say so to
+adb.** They used a bare `adb install`, which with exactly one device
+attached picks that device whatever it is — so with a phone plugged in
+and no emulator running, the task whose summary reads "in the Android
+Emulator" installed on the phone. They pass `--target emulator` and
+refuse with `make android-emulator` as the remedy.
+
+**`DEVICE_ID=<serial>` still names a device, and several attached
+devices is now an error rather than a silent pick of the first.**
+
 Two are deliberately **not** wrapped. `android:logs` greps logcat for
 `(Wails|yellowjacket)`, which catches the `WailsBridge` tag but misses
 the app's own process tag (`app.yellowjacket` — lowercase, so `Wails`
@@ -269,16 +303,51 @@ instead. And `ensure-emulator` boots whatever `-list-avds | tail -1`
 returns, with no pidfile and no boot wait, so it cannot be stopped or
 sequenced.
 
-## The identity is declared twice
+## The identity is read back from the APK
 
+It used to be **declared twice**, and that is what #159 was.
 `applicationId` in `build/android/app/build.gradle` is what Gradle
-installs. `APP_ID` in `build/android/Taskfile.yml` is what every
-adb-driven task uninstalls, launches and filters. **Nothing enforces
-that they agree**, and `ANDROID.md`'s advice to set `APP_ID` in
-`build/config.yml` does not work in beta.8 — `wails3 task` never reads
-that file (verified with `--dry`), and even when set it feeds only the
-adb commands, never Gradle. Change both or the official `run`/`deploy`
-tasks address a package that is not installed.
+installs; `APP_ID` in `build/android/Taskfile.yml` was what every
+adb-driven task uninstalled, launched and filtered, and nothing
+enforced that they agree. They did not: the debug buildType carries
+`applicationIdSuffix ".dev"`, so every task that assembles a debug APK
+addressed the release id. This file flagged the hazard for five phases
+and it cashed out twice — once as a wrong `am start`, once as an
+uninstall of the user's library.
+
+**`scripts/android-pkgid.sh` is the one answer now.** It prints the
+package id an APK declares (`aapt2 dump packagename`, falling back to
+`aapt dump badging`), and the deploy path installs and launches *that*.
+The APK is the authority because the task that installs it has just
+built it: whatever Gradle resolved the applicationId to, suffixes and
+flavours included, is in the file, and no default can disagree with it.
+An APK it cannot read is a hard failure, never a fallback to a written
+down default — guessing is the bug.
+
+**`APP_ID` survives as an assertion, not a setting**, and has no
+default. `wails3 task android:run APP_ID=app.yellowjacket` says "this
+build had better declare that id" and is refused, naming both, *before*
+anything is installed or a device is even chosen. It could never have
+been a setting: `ANDROID.md`'s advice to put it in `build/config.yml`
+does not work in beta.8 — `wails3 task` never reads that file (verified
+with `--dry`) — and even when set it fed only the adb commands, never
+Gradle.
+
+`scripts/android-emulator.sh` derives `PKG` the same way, from
+`bin/yellowjacket.apk` when one is built, so `make android-install`,
+`android-launch`, `android-logs` and `android-smoke` follow whichever
+variant is actually in `bin/`. `YJ_ANDROID_PKG` still overrides, and
+the old literal survives only for a tree with no APK built yet.
+
+**The uninstall is gone and is not coming back.** It existed to make
+the bare `install` on the next line work at all — without `-r` Android
+refuses an install over an existing package — so `install -r` removes
+the *reason* for it rather than merely removing it. What is left is the
+one case an uninstall really is the remedy, a changed signing
+certificate, and that is exactly the case where performing it silently
+costs the user their library. So it is named and not done, which is the
+answer `scripts/android-emulator.sh` had already reached for
+`make android-install`.
 
 Related, and it will bite once: the launcher activity is
 `com.wails.app.MainActivity` and the applicationId is
@@ -287,6 +356,27 @@ resolves the leading dot against the *applicationId* and fails with a
 class-not-found that reads like a broken build. Always the
 fully-qualified form.
 
+**`wails3 task android:run:device` is the way to put a debug build on a
+real device**, since #159. What #52 used, before it was safe, was the
+longer form, and it is still the smallest thing that works if you want
+no script between you and adb:
+
+```bash
+wails3 task android:build ARCH=arm64 && wails3 task android:assemble:apk
+adb install -r bin/yellowjacket.apk      # -r, never uninstall
+adb shell am start -n app.yellowjacket.dev/com.wails.app.MainActivity
+```
+
+The id in that last line is the one thing to keep an eye on by hand —
+`./scripts/android-pkgid.sh bin/yellowjacket.apk` is what the tasks ask,
+and it is a good habit before any `am start` written out in full.
+
+`YJ_ANDROID_PKG=app.yellowjacket.dev` still overrides what
+`scripts/android-emulator.sh` — and therefore `make android-smoke`,
+`android-logs`, `android-launch` — addresses, but it is rarely needed
+now: that default is read from `bin/yellowjacket.apk`, so it already
+follows whichever variant was built last.
+
 ## What only a device can answer
 
 The emulator cannot run this app (three separate reasons, none of them
@@ -311,6 +401,91 @@ system bars, the back gesture, focus and audio interruptions,
 permission dialogs, the keyboard — not about what the app draws. The
 drawing is what the other five tiers already cover.
 
+**The third such fault was the activity lifecycle** (#52), and it is
+the one to re-check after touching `main()`, `WailsBridge` or
+`MainActivity`. Android destroys and recreates an activity **without
+restarting the process**, and Wails' `nativeInit` — which
+`MainActivity.onCreate` calls — runs `go mainFunc()` every time. So
+Go's `main()` ran again on a live app, `app.Run()` refused (`a.starting`
+is still true behind Android's `select{}`), and the `os.Exit(1)` under
+it took the healthy first app down with it.
+
+### The lifecycle check, and how to trigger it on demand
+
+This is the regression guard for #52 on this tier, because no other
+tier runs `main()` on Android at all. The Go-side guard
+(`TestMainClaimsBeforeItDoesAnything`) catches work creeping above the
+latch; only the device catches the latch not working.
+
+**Trigger a relaunch with a configuration change the manifest does not
+declare.** `AndroidManifest.xml` lists
+`orientation|screenSize|keyboardHidden|uiMode`, so those are handled
+in-place and are *not* triggers. `fontScale` is not listed, and it is a
+one-liner:
+
+```bash
+adb shell settings put system font_scale 1.15   # restore the old value after
+```
+
+That is the same in-process destroy/recreate that "Don't keep
+activities", a locale change and a memory trim produce, but on demand.
+
+**"Don't keep activities" is the report's own lever and did not work on
+this device**: `settings put global always_finish_activities 1` reads
+back as `1`, `am set-always-finish-activities` does not exist on this
+build, and the activity was never finished on backgrounding. Do not
+spend an afternoon on it; use the config change.
+
+**The assertion is the pid, and the tell is two bridge inits in one.**
+
+```bash
+adb logcat -d | grep -E "Wails bridge initialized|has died|finishDrawing of relaunch"
+```
+
+Healthy is one pid appearing twice — the process surviving the
+recreation:
+
+```
+I/WailsBridge(28420): Wails bridge initialized
+I/WailsBridge(28420): Wails bridge initialized     <- same pid, recreated
+```
+
+Broken is that pair followed within a second by:
+
+```
+I/WindowManager: finishDrawing of relaunch: Window{...MainActivity} 603ms
+I/ActivityManager: Process app.yellowjacket.dev (pid 22956) has died: fg  TOP
+W/ActivityTaskManager: Force removing ActivityRecord{...}: app died, no saved state
+```
+
+Two things about reading that. **`has died: fg  TOP` is not a memory
+kill** — the system does not reclaim the foreground process, so this is
+the app leaving of its own accord. And there is **no crash record
+anywhere**: `logcat -b crash` is empty, no `AndroidRuntime`, no
+`libc: Fatal signal`, no tombstone. That is the `os.Exit` signature,
+and it is why "the system killed it" is the wrong first hypothesis.
+
+**Surviving is only half of it — check the recreated WebView is still
+wired to the running app.** A plausible-looking fix (making
+`WailsBridge.initialized` static, so the second `nativeInit` is skipped)
+keeps the process alive and silently breaks this, because `nativeInit`
+is also what re-points the JNI reference at the new bridge. Go would go
+on executing JavaScript against the destroyed activity's WebView: the
+app opens, renders, and never receives another backend event.
+
+Ask the page, after a relaunch and a resume:
+
+```bash
+make android-inspect
+make android-eval EXPR='(()=>{window.__probe=[];const o=window._wails.dispatchWailsEvent.bind(window._wails);window._wails.dispatchWailsEvent=(e)=>{window.__probe.push(e&&e.name);return o(e)};return "ok"})()'
+# background and foreground the app, then:
+make android-eval EXPR='JSON.stringify(window.__probe)'
+```
+
+A healthy build answers with events from the live services —
+`["IndexStatusChanged","JobsChanged","JobsChanged","android:storageAccess"]`.
+`[]` means the bridge reference is stale.
+
 ## Asking the device, not just looking at it
 
 A real phone can be inspected, and that turns this tier from "reported

.planning/NOTES.md

@@ -4077,3 +4077,168 @@ have saved the other two cycles.
 first track with no cover art" selects nothing in particular. The
 placeholder's presence is asserted instead, which is the property the
 test actually depends on.
+
+## An activity recreation kills the process, deterministically (measured 2026-08-20)
+
+#52's report was "sometimes crashes or restarts when reopened after
+running in the background". Measured on a real device, the *fault* is
+not intermittent at all — only its trigger is.
+
+Device: Light Phone III (TLP301), Android 14 / SDK 34, arm64-v8a,
+WebView **Chrome 113** at 424x439 CSS px. Debug build
+(`app.yellowjacket.dev`), installed beside the released `v0.3.1` with
+`install -r`.
+
+**Conditional on the activity actually being recreated in a live
+process, the process died 8 times out of 8** — 3 by hand, then 5/5 in a
+scripted loop. The runs where it survived were runs where no recreation
+happened (one `Wails bridge initialized` in the log rather than two), so
+they are inconclusive rather than passes; a harness that does not check
+for the second init reports those as green and reads as flakiness.
+After the fix: 5/5 recreations survived, plus 6 background/foreground
+cycles and 3 interleaved recreations on one pid.
+
+The mechanism is three log lines:
+
+```
+12:47:56.159 I/WailsBridge(22956): Wails bridge initialized
+12:48:38.898 I/WailsBridge(22956): Wails bridge initialized   <- same pid
+12:48:39.357 I/ActivityManager: Process app.yellowjacket.dev (pid 22956) has died: fg  TOP
+```
+
+`nativeInit` runs `go mainFunc()` on every activity creation; the second
+`main()` reaches `app.Run()`, which refuses because `a.starting` is
+still true behind Android's `select{}`, and `os.Exit(1)` takes the whole
+process — including the healthy first app — with it.
+
+Four things worth keeping:
+
+- **`has died: fg  TOP` is not a memory kill.** The system does not
+  reclaim the foreground process. This reads as "the OS killed us",
+  which is the wrong hypothesis and the reason the issue sat unverified.
+- **There is no crash record of any kind**: `logcat -b crash` empty, no
+  `AndroidRuntime`, no `libc: Fatal signal`, no tombstone. `os.Exit` is
+  not a crash. The one line that named the fault —
+  `slog.Error("application error", "err", ...)`, carrying
+  `"application is running or a previous run has failed"` — went to
+  `/dev/null`. That is #160.
+- **"Don't keep activities" does not work on this device.**
+  `settings put global always_finish_activities 1` reads back as `1`,
+  `am set-always-finish-activities` does not exist on this build, and
+  the activity was never finished on backgrounding. The report's own
+  suggested lever is a dead end here. What *does* work, deterministically
+  and in one line, is a configuration change the manifest does not
+  declare: `adb shell settings put system font_scale 1.15`
+  (`AndroidManifest.xml` declares `orientation|screenSize|
+  keyboardHidden|uiMode`, so none of those are triggers).
+- **Surviving is only half the property.** The recreated WebView has to
+  still be wired to the running app, which was verified by hooking
+  `window._wails.dispatchWailsEvent` and backgrounding/foregrounding:
+  `["IndexStatusChanged","JobsChanged","JobsChanged",
+  "android:storageAccess"]`. The tempting Java-side fix — making
+  `WailsBridge.initialized` static — passes the pid check and fails
+  this one, because `nativeInit` is also what re-points the JNI
+  reference at the new bridge.
+
+## The Taskfile's device tasks uninstall the released app (2026-08-20)
+
+`android:run:device` builds the **debug** variant
+(`applicationIdSuffix ".dev"`) and then runs
+`adb uninstall {{.APP_ID}}`, where `APP_ID` defaults to
+`app.yellowjacket` — the **release** id. So it deletes the user's
+installed app and its library, installs a different package, and then
+fails to launch the one it removed. `deploy-device` carries the same
+uninstall. Filed as #159; `android-tier.md` had been recommending
+`run:device` as the way onto a device.
+
+This is the hazard that file already names — "The identity is declared
+twice ... **Nothing enforces that they agree**" — reached by a second
+route: the two ids differ not because someone edited one, but because
+the debug buildType suffixes it.
+
+## The uninstall was there to make a bare `install` work (measured 2026-08-20)
+
+Fixing #159 turned up *why* the `adb uninstall` was in all four tasks,
+which the issue does not say and which decides whether it can simply be
+deleted. The line under it was `adb install`, with **no `-r`** — and
+Android refuses an install over an existing package without it. So the
+uninstall was not a deliberate clean-slate step; it was the price of
+the missing flag, paid on every run, and `install -r` removes the
+reason for it rather than merely removing it.
+
+That matters because "should the uninstall go at all" looked like a
+trade — drop it and a signing-certificate change fails with
+`INSTALL_FAILED_UPDATE_INCOMPATIBLE` instead of being handled. It is
+not a trade: nothing else was relying on it. The certificate case is
+reported with the command to run, which is what
+`scripts/android-emulator.sh` already did for `make android-install`,
+so this is one existing judgement applied consistently rather than a
+new one.
+
+## `wails3 task android:run` installs on a phone (measured 2026-08-20)
+
+The emulator tasks (`run`, `deploy-emulator`) used a bare `adb install`
+with no `-s`. adb with exactly one device attached uses that device
+whatever kind it is, so with a phone plugged in and no emulator
+running, the task whose summary reads "in the Android Emulator"
+installed on the phone — and, before #159 was fixed, ran
+`adb uninstall app.yellowjacket` against it first. The reported data
+loss was reachable from the *emulator* task, which is not what the
+issue describes and is worse, because nothing in the name warns you.
+
+Measured after the fix, phone attached and emulator stopped:
+
+```
+$ ./scripts/android-deploy.sh --apk bin/yellowjacket.apk --target emulator
+android-deploy: no emulator target is online.
+    LP3LHMA531900746	device
+    Start one with:  make android-emulator
+```
+
+The general form: **a task that names a target has to say so to adb.**
+The device tasks always filtered on `$1 !~ /^emulator-/`; the emulator
+tasks filtered on nothing at all.
+
+## The package id can be read back, and costs nothing (2026-08-20)
+
+`aapt2 dump packagename <apk>` answers in one word and ~40 ms, from
+`$ANDROID_HOME/build-tools/*/aapt2` (versioned, so resolved not
+pinned); `aapt dump badging` is the fallback for older build-tools and
+is what #159's own measurement used. That is cheap enough to do on
+every deploy, which is what makes "the two ids agree by construction"
+affordable rather than aspirational — the alternative considered was
+giving the debug-flavoured tasks `APP_ID` + `.dev`, which is one line
+and leaves the class of bug alive for the next flavour or suffix.
+
+The guard runs **before** a target is chosen, deliberately: it is a
+question about the artifact, so it can be exercised with nothing
+plugged in, and a build whose id is wrong should be refused whether or
+not there is anything to install it onto. That is what let the negative
+test run safely with the user's phone attached:
+
+```
+$ ./scripts/android-deploy.sh --apk bin/yellowjacket.apk \
+      --target device --expect app.yellowjacket
+android-pkgid: refusing to act on a package this APK does not declare.
+    the APK declares:  app.yellowjacket.dev
+    the task expects:  app.yellowjacket
+rc=2
+```
+
+That is exactly #159's configuration — debug APK, release id, real
+device — refused with no adb call made.
+
+## `make android-emulator`'s boot wait can be satisfied by a phone (2026-08-20)
+
+Noticed while booting the emulator for #159's verification, with a
+phone also attached. `scripts/android-emulator.sh start` reported
+`waiting for boot ok / android 14` about **eight seconds** after
+launching the emulator, which had not appeared in `adb devices` yet —
+`pick_device`'s last resort is "exactly one device online", and at that
+moment the one online device was the phone. So it waited for the
+phone's boot, found it long since booted, and returned. The emulator
+took another ~10 s to come up.
+
+Harmless here (the emulator was up before anything used it) and a
+straightforward race otherwise: `start` should wait for a device that
+is an emulator, not for whatever `pick_device` returns. Filed as #162.

CLAUDE.md

@@ -317,6 +317,60 @@ stacking dialogs. Window state moved off that path entirely, onto a
 window still exists and `OnShutdown` has neither a context nor a
 window.
 
+**An activity is a view onto the process, and `main()` runs once per
+process.** On Android the Wails entry point is `nativeInit`, which
+`MainActivity.onCreate` calls — and it does two things: it re-points the
+native library's global JNI reference at the calling `WailsBridge`, and
+it runs `go mainFunc()`. Android destroys and recreates an activity
+**without restarting the process** (a configuration change the manifest
+does not declare, memory pressure, or every background under "Don't keep
+activities"), so `main()` ran again on a live app. `application.New`
+returns the *existing* app rather than building a second one,
+`app.Run()` then refuses — `a.starting` is still true, because Android's
+`platformRun` is `select{}` and never returns — and the `os.Exit(1)`
+under that error took the **first**, healthy app down with it: its
+database, its queue, and the audio a `mediaPlayback` foreground service
+was holding the process alive to play. `mainStarted` latches it, first
+statement in `main()`.
+
+Four things about it are load-bearing.
+
+**The answer to "restore the session or cold-start" is settled by
+playback, not by preference.** The audio lives in the Go process, so a
+cold start on every activity recreation would stop the music mid-song —
+which is the exact thing the foreground service exists to prevent. The
+activity is a view; the app is the process. The frontend already
+cooperates, because a recreated WebView loads the page fresh and fetches
+its state from a backend that never went away.
+
+**Returning early is not a degraded mode, and that is why the latch is
+in Go rather than in Java.** The obvious fix — making
+`WailsBridge.initialized` `static`, so the second `nativeInit` is
+skipped — keeps the process alive and silently breaks the app, because
+skipping `nativeInit` skips the reference re-point too: Go would keep
+executing JavaScript against the *destroyed* activity's WebView, and the
+app would open, render, and never receive another backend event. The
+latch lets `nativeInit` do its first job and declines only its second.
+
+**`ServiceShutdown` has never run on Android**, and nothing should be
+built on the assumption that it will. `App.Quit()` reaches an
+`androidApp.destroy()` that is an empty method, and `Run()`'s deferred
+`shutdownServices()` cannot fire behind `select{}`. Durability on this
+platform is the persist writers, which submit on every mutation rather
+than at exit — which is also why `MainActivity.onDestroy` no longer
+calls `bridge.shutdown()`: the activity going away is not the app
+shutting down, and there is no callback for the process going away
+because Android simply kills it.
+
+**No tier here can see any of this**, so the guard is split. A source
+sweep (`TestMainClaimsBeforeItDoesAnything`) asserts the latch is the
+*first* statement of `main()` — the failure it exists for is not
+deletion, which is loud, but a line creeping in above it, since a second
+`NewYellowJacketApp` opens the SQLite database again on every
+recreation. The rest is a documented device check in
+`.pi/skills/yellowjacket-dev/references/android-tier.md`, with the
+logcat signature and a one-line way to force a recreation.
+
 `internalServiceMethods` auto-excludes `ServiceStartup`,
 `ServiceShutdown`, `ServiceName` and `ServeHTTP` from bindings, so this
 shape **removed** 12 spurious bindings and the bogus `context` model

build/android/Taskfile.yml

@@ -4,18 +4,28 @@ includes:
   common: ../Taskfile.yml
 
 vars:
-  # The *installed* package name, which every adb-driven task below uses
-  # to uninstall, launch and filter. It must agree with `applicationId`
-  # in app/build.gradle, and nothing enforces that.
+  # APP_ID is an *assertion*, not a setting, and it has no default.
   #
-  # ANDROID.md says to set this in build/config.yml. That does not work
-  # in beta.8, checked both ways: `wails3 task` builds its var set from
-  # CLI KEY=VALUE arguments and the Taskfile tree only -- nothing reads
-  # config.yml -- and even when set it feeds only these adb commands,
-  # never Gradle. So the identity is declared twice, here and in
-  # build.gradle, and a change to one alone means the official run and
-  # deploy tasks address a package that is not installed.
-  APP_ID: '{{.APP_ID | default "app.yellowjacket"}}'
+  # It used to be the id every adb-driven task below uninstalled,
+  # launched and filtered, defaulting to "app.yellowjacket". It could
+  # never have been a setting: `wails3 task` builds its var set from CLI
+  # KEY=VALUE arguments and the Taskfile tree only -- nothing reads
+  # build/config.yml, contrary to ANDROID.md, checked with --dry -- and
+  # even when set it fed only the adb commands, never Gradle. So the
+  # identity was declared twice, here and as `applicationId` in
+  # app/build.gradle, with nothing enforcing that they agree.
+  #
+  # They did not agree. The debug buildType carries
+  # `applicationIdSuffix ".dev"`, so the tasks that assemble a debug APK
+  # addressed the *release* id -- on a device, the user's installed app
+  # and their library (#159).
+  #
+  # The id is now read back from the built APK by scripts/android-
+  # pkgid.sh, so the thing installed and the thing launched agree by
+  # construction. Passing APP_ID= says "this build had better declare
+  # that id", and the deploy refuses before touching anything if it does
+  # not -- which is the check that would have caught #159 statically.
+  APP_ID: '{{.APP_ID | default ""}}'
   MIN_SDK: '21'
   TARGET_SDK: '35'
   # The emulator runs the host architecture; physical devices are arm64
@@ -372,9 +382,7 @@ tasks:
           ARCH: '{{.ARCH | default .HOST_ARCH}}'
     cmds:
       - task: ensure-emulator
-      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
-      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
-      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target emulator{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
 
   run:
     summary: Build, install and launch a debug build in the Android Emulator
@@ -383,9 +391,7 @@ tasks:
       - task: build
     cmds:
       - task: assemble:apk
-      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
-      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
-      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target emulator{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
 
   device:list:
     summary: Lists connected Android devices and emulators (serials)
@@ -400,25 +406,7 @@ tasks:
           ARCH: arm64
     cmds:
       - task: assemble:apk
-      - |
-        DEVICE='{{.DEVICE_ID | default ""}}'
-        if [ -z "$DEVICE" ]; then
-          DEVICE="${DEVICE_ID:-}"
-        fi
-        if [ -z "$DEVICE" ]; then
-          DEVICE=$("{{.ADB}}" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1; exit }')
-        fi
-        if [ -z "$DEVICE" ]; then
-          echo "Error: no connected physical Android device found."
-          echo "Pass DEVICE_ID=<serial> to target a device explicitly."
-          echo "Find connected device serials with: {{.ADB}} devices"
-          exit 1
-        fi
-
-        echo "Deploying {{.BIN_DIR}}/{{.APP_NAME}}.apk to device $DEVICE..."
-        "{{.ADB}}" -s "$DEVICE" uninstall {{.APP_ID}} 2>/dev/null || true
-        "{{.ADB}}" -s "$DEVICE" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"
-        "{{.ADB}}" -s "$DEVICE" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target device{{if .DEVICE_ID}} --serial "{{.DEVICE_ID}}"{{end}}{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
     preconditions:
       - sh: '[ -x "{{.ADB}}" ] || command -v adb'
         msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"
@@ -430,25 +418,7 @@ tasks:
         vars:
           ARCH: arm64
     cmds:
-      - |
-        DEVICE='{{.DEVICE_ID | default ""}}'
-        if [ -z "$DEVICE" ]; then
-          DEVICE="${DEVICE_ID:-}"
-        fi
-        if [ -z "$DEVICE" ]; then
-          DEVICE=$("{{.ADB}}" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1; exit }')
-        fi
-        if [ -z "$DEVICE" ]; then
-          echo "Error: no connected physical Android device found."
-          echo "Pass DEVICE_ID=<serial> to target a device explicitly."
-          echo "Find connected device serials with: {{.ADB}} devices"
-          exit 1
-        fi
-
-        echo "Deploying {{.BIN_DIR}}/{{.APP_NAME}}.apk to device $DEVICE..."
-        "{{.ADB}}" -s "$DEVICE" uninstall {{.APP_ID}} 2>/dev/null || true
-        "{{.ADB}}" -s "$DEVICE" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"
-        "{{.ADB}}" -s "$DEVICE" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity
+      - './scripts/android-deploy.sh --apk "{{.BIN_DIR}}/{{.APP_NAME}}.apk" --target device{{if .DEVICE_ID}} --serial "{{.DEVICE_ID}}"{{end}}{{if .APP_ID}} --expect "{{.APP_ID}}"{{end}}'
     preconditions:
       - sh: '[ -x "{{.ADB}}" ] || command -v adb'
         msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"

build/android/app/src/main/java/com/wails/app/MainActivity.java

@@ -891,13 +891,41 @@ public class MainActivity extends AppCompatActivity {
         }
     }
 
+    /**
+     * The activity going away is not the app shutting down.
+     *
+     * <p>The scaffold called {@code bridge.shutdown()} here, which is
+     * the natural reading of onDestroy and is wrong for this app twice
+     * over. Android destroys and recreates an activity for a
+     * configuration change the manifest does not declare, under memory
+     * pressure, and on every background if the user has "Don't keep
+     * activities" on -- all **without restarting the process**. And
+     * when the user really does leave, this app's reason for existing
+     * in the background is that a song is playing, which is what the
+     * {@code mediaPlayback} foreground service is holding the process
+     * alive for. Either way, tearing the Go side down here would stop
+     * the music.
+     *
+     * <p>It was harmless only by accident: {@code nativeShutdown} calls
+     * {@code App.Quit()}, whose Android {@code destroy()} is an empty
+     * method, and {@code Run()}'s deferred {@code shutdownServices()}
+     * can never fire because Android's {@code platformRun} is
+     * {@code select{}} and does not return. So no {@code
+     * ServiceShutdown} has ever run on Android, and removing this call
+     * changes nothing today -- it stops the day someone implements
+     * {@code destroy()} from silently killing playback on a rotation.
+     *
+     * <p>There is no callback for "the process is going away"; Android
+     * simply kills it. Durability on this platform is the persist
+     * writers, which submit on every mutation rather than at exit.
+     *
+     * <p>See #52, and CLAUDE.md, "An activity is a view onto the
+     * process".
+     */
     @Override
     protected void onDestroy() {
         super.onDestroy();
         unregisterSystemEventReceivers();
-        if (bridge != null) {
-            bridge.shutdown();
-        }
         if (webView != null) {
             webView.destroy();
         }

build/android/app/src/main/java/com/wails/app/WailsBridge.java

@@ -129,7 +129,24 @@ public class WailsBridge {
     }
 
     /**
-     * Initialize the native Go library
+     * Initialize the native Go library.
+     *
+     * <p><b>{@code initialized} is deliberately per-instance, and making
+     * it {@code static} is the trap this comment exists for.</b> A
+     * recreated activity builds a new bridge and calls this again, in a
+     * process where the native library is already loaded and Go's
+     * {@code main()} is already running -- so "initialise once per
+     * process" looks like exactly the right rule. It is not, because
+     * {@code nativeInit} does <i>two</i> things: it runs
+     * {@code go mainFunc()}, and it stores the global JNI reference to
+     * <i>this</i> bridge. Skip it and Go keeps executing JavaScript
+     * against the destroyed activity's WebView: the app opens, renders,
+     * and never receives another backend event.
+     *
+     * <p>So this is called every time, and the half that must not repeat
+     * is latched on the Go side instead, at the top of {@code main()} --
+     * which is also where the damage was ({@code os.Exit(1)}), and the
+     * only place that can see it. See #52.
      */
     public void initialize() {
         if (initialized) {

main.go

@@ -6,6 +6,7 @@ import (
 	"log/slog"
 	"os"
 	"strings"
+	"sync/atomic"
 
 	"github.com/golang-cz/devslog"
 	"github.com/wailsapp/wails/v3/pkg/application"
@@ -28,7 +29,61 @@ var (
 //go:embed all:frontend/dist
 var frontendDistAssets embed.FS
 
+// mainStarted latches the first entry into main().
+//
+// **On Android main() is called once per *activity*, and the process
+// outlives the activity.** Wails' JNI entry point is
+// `nativeInit`, which does two things: it re-points the native
+// library's global reference at the calling `WailsBridge`, and it runs
+// `go mainFunc()`. `MainActivity.onCreate` calls it, and Android
+// recreates the activity — for a configuration change it does not
+// declare, under memory pressure, or on every single background when
+// the user has "Don't keep activities" switched on — **without
+// restarting the process**.
+//
+// So main() ran again, on a live app, and every path out of that is
+// fatal:
+//
+//   - `application.New` returns the *existing* `globalApplication` when
+//     there is one, silently discarding the second set of Services.
+//   - `app.Run()` then refuses, by design: `a.starting` is still true,
+//     because Android's `platformRun` is `select{}` and never returns.
+//     It answers "application is running or a previous run has failed".
+//   - which lands on `os.Exit(1)` at the foot of this function, and
+//     that takes down the **first**, perfectly healthy app with it —
+//     its database, its queue, and the audio that a foreground service
+//     is holding the process alive to play.
+//
+// ActivityManager then restarts the app, which is the report: "crashes
+// or restarts when reopened after running in the background". It never
+// left a tombstone because `os.Exit` is not a crash, and it never left
+// a log line because an Android app's fd 1 goes to /dev/null.
+//
+// The latch is the whole fix, and it has to be **first**: everything
+// below it — `NewYellowJacketApp` above all, which opens the SQLite
+// database — is work that must not happen twice in one process.
+// Returning early is not a degraded mode: `nativeInit` has already
+// re-attached the bridge, so the recreated activity's WebView talks to
+// the app that is still running, with its queue and its playback
+// position intact. See CLAUDE.md, "An activity is a view onto the
+// process".
+//
+// It is inert off Android, where a process has exactly one main().
+var mainStarted atomic.Bool
+
+// claimMainOnce reports whether this is the first call to main() in
+// this process. See mainStarted.
+func claimMainOnce() bool {
+	return mainStarted.CompareAndSwap(false, true)
+}
+
 func main() {
+	// Android calls main() once per activity, and the process outlives
+	// the activity. Nothing below this line may run twice.
+	if !claimMainOnce() {
+		return
+	}
+
 	// **Mobile has no home directory, and this must run before anything
 	// asks for a path.** backend/system resolves config and data from
 	// $HOME or the OS equivalent, and on Android there is neither: its

main_test.go

@@ -0,0 +1,104 @@
+package main
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"testing"
+)
+
+// TestMainRunsOncePerProcess pins the latch itself.
+func TestMainRunsOncePerProcess(t *testing.T) {
+	t.Parallel()
+
+	mainStarted.Store(false)
+
+	if !claimMainOnce() {
+		t.Fatal("the first call to claimMainOnce must claim it")
+	}
+
+	if claimMainOnce() {
+		t.Fatal("a second call to claimMainOnce must not claim it: " +
+			"on Android that second call is a second main() in a live " +
+			"process, and every path out of it ends in os.Exit(1)")
+	}
+}
+
+// TestMainClaimsBeforeItDoesAnything is the assertion that actually
+// guards #52, and it is a source sweep for the reason
+// TestNoDirectRuntimeEmits is: no tier here runs main() on Android, so
+// nothing else can see work creeping in above the latch.
+//
+// The failure it exists for is not the latch being deleted — that is
+// loud. It is a line being added above it: a second
+// NewYellowJacketApp opens the SQLite database a second time in one
+// process, and it would do so on every activity recreation, silently,
+// on a build that otherwise looks entirely healthy.
+func TestMainClaimsBeforeItDoesAnything(t *testing.T) {
+	t.Parallel()
+
+	fset := token.NewFileSet()
+
+	file, err := parser.ParseFile(fset, "main.go", nil, 0)
+	if err != nil {
+		t.Fatalf("parse main.go: %v", err)
+	}
+
+	var fn *ast.FuncDecl
+
+	for _, decl := range file.Decls {
+		d, ok := decl.(*ast.FuncDecl)
+		if ok && d.Name.Name == "main" && d.Recv == nil {
+			fn = d
+
+			break
+		}
+	}
+
+	if fn == nil {
+		t.Fatal("no func main in main.go — this test read the wrong file")
+	}
+
+	if len(fn.Body.List) == 0 {
+		t.Fatal("func main is empty")
+	}
+
+	if !claimsMainOnce(fn.Body.List[0]) {
+		t.Fatalf("the first statement of main() must be the "+
+			"`if !claimMainOnce() { return }` guard, got %T — see #52: "+
+			"Android calls main() once per activity, in a process that "+
+			"outlives the activity, so anything above the guard runs "+
+			"again on every recreation", fn.Body.List[0])
+	}
+}
+
+// claimsMainOnce reports whether stmt is `if !claimMainOnce() { return }`.
+func claimsMainOnce(stmt ast.Stmt) bool {
+	ifStmt, ok := stmt.(*ast.IfStmt)
+	if !ok {
+		return false
+	}
+
+	unary, ok := ifStmt.Cond.(*ast.UnaryExpr)
+	if !ok || unary.Op != token.NOT {
+		return false
+	}
+
+	call, ok := unary.X.(*ast.CallExpr)
+	if !ok {
+		return false
+	}
+
+	ident, ok := call.Fun.(*ast.Ident)
+	if !ok || ident.Name != "claimMainOnce" {
+		return false
+	}
+
+	if len(ifStmt.Body.List) != 1 {
+		return false
+	}
+
+	_, ok = ifStmt.Body.List[0].(*ast.ReturnStmt)
+
+	return ok
+}

scripts/android-deploy.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+#
+# Install a built APK onto an Android target and launch it, under the
+# package id the APK itself declares.
+#
+# This is the whole body of build/android/Taskfile.yml's four adb-driven
+# tasks — deploy-emulator, run, run:device, deploy-device — which were
+# three lines each, written out four times, and wrong in two ways in all
+# four (#159):
+#
+#   adb uninstall app.yellowjacket    # the RELEASE id, unconditionally
+#   adb install    bin/yellowjacket.apk
+#   adb shell am start -n app.yellowjacket/com.wails.app.MainActivity
+#
+# **The uninstall is not here and does not come back.**  It was there to
+# make the bare `install` on the next line work at all — without -r,
+# Android refuses an install over an existing package — so `install -r`
+# removes the reason for it rather than merely removing it.  What is
+# left is the one case an uninstall really is the remedy, a changed
+# signing certificate, and that is exactly the case where performing it
+# silently costs the user their library.  So it is *named* and not done:
+# an error message carrying the command is a decision the person at the
+# keyboard gets to make, which is the same answer scripts/android-
+# emulator.sh already reached for `make android-install`.
+#
+# **The id is read back from the artifact**, never defaulted, so the
+# thing installed and the thing launched cannot disagree — see
+# scripts/android-pkgid.sh for why that is by construction rather than
+# by discipline.
+#
+# **The target is checked against the task's own name.**  The emulator
+# tasks used a bare `adb`, which with one device attached picks that
+# device whatever it is — so `wails3 task android:run`, whose summary
+# says "in the Android Emulator", installed on the phone when a phone
+# was the only thing plugged in.  A task addressing something other than
+# what it says is the same fault as the package id, one level up.
+#
+# Usage:
+#   android-deploy.sh --apk <path> --target emulator|device|any \
+#                     [--expect <id>] [--serial <s>] [--no-launch]
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+SDK="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$HOME/Android/Sdk}}"
+ADB="$(command -v adb || echo "$SDK/platform-tools/adb")"
+
+# **Not "$PKG/.MainActivity".**  A leading-dot activity is resolved
+# against the applicationId, and the scaffold's activity lives in the
+# Java package com.wails.app, which is deliberately not it.  The short
+# form fails with a class-not-found that reads like a broken build.
+ACTIVITY="${YJ_ANDROID_ACTIVITY:-com.wails.app.MainActivity}"
+
+APK=""
+TARGET="any"
+EXPECT=""
+SERIAL="${ANDROID_SERIAL:-${DEVICE_ID:-}}"
+LAUNCH=1
+
+die() { echo "android-deploy: $*" >&2; exit 1; }
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+	--apk) APK="${2:-}"; shift 2 ;;
+	--target) TARGET="${2:-}"; shift 2 ;;
+	--expect) EXPECT="${2:-}"; shift 2 ;;
+	--serial) SERIAL="${2:-}"; shift 2 ;;
+	--no-launch) LAUNCH=0; shift ;;
+	*) die "unknown option $1" ;;
+	esac
+done
+
+[ -n "$APK" ] || die "--apk is required"
+[ -f "$APK" ] || die "no such APK: $APK
+    Build one first:  wails3 task android:assemble:apk   (debug)
+                      wails3 task android:package        (release)"
+[ -x "$ADB" ] || command -v adb >/dev/null ||
+	die "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"
+
+case "$TARGET" in
+emulator | device | any) ;;
+*) die "--target must be emulator, device or any (got '$TARGET')" ;;
+esac
+
+# ---------------------------------------------------------------- #
+# Which package
+# ---------------------------------------------------------------- #
+
+# This runs *before* a target is chosen, deliberately: the guard is a
+# question about the artifact, so it can be answered — and exercised —
+# with nothing plugged in, and a build whose id is wrong should be
+# refused whether or not there is anything to install it onto.
+#
+# An unreadable APK, or an id that is not the one the caller named, is a
+# hard stop before anything is installed or launched.  Spelled as two
+# calls rather than one with a conditional argument: an empty array under
+# `set -u` is an unbound variable in bash 3.2, which is what macOS ships.
+if [ -n "$EXPECT" ]; then
+	PKG="$(./scripts/android-pkgid.sh "$APK" --expect "$EXPECT")"
+else
+	PKG="$(./scripts/android-pkgid.sh "$APK")"
+fi
+
+# ---------------------------------------------------------------- #
+# Which target
+# ---------------------------------------------------------------- #
+
+# An emulator serial is "emulator-<port>"; anything else online is a
+# physical device.  That is the same test the device tasks already made,
+# and the emulator tasks did not make at all.
+online_matching() {
+	case "$TARGET" in
+	emulator) "$ADB" devices | awk 'NR > 1 && $2 == "device" && $1 ~ /^emulator-/ { print $1 }' ;;
+	device) "$ADB" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1 }' ;;
+	any) "$ADB" devices | awk 'NR > 1 && $2 == "device" { print $1 }' ;;
+	esac
+}
+
+if [ -z "$SERIAL" ]; then
+	matches="$(online_matching)"
+	count="$(printf '%s' "$matches" | grep -c . || true)"
+
+	if [ "$count" -eq 0 ]; then
+		echo "android-deploy: no ${TARGET/any/attached} target is online." >&2
+		"$ADB" devices | sed '1d;/^$/d;s/^/    /' >&2 || true
+		if [ "$TARGET" = "emulator" ]; then
+			echo "    Start one with:  make android-emulator" >&2
+		elif [ "$TARGET" = "device" ]; then
+			echo "    Plug a phone in and authorise the adb key." >&2
+		fi
+		exit 1
+	fi
+
+	# Several is ambiguous, and picking the first silently is how a
+	# build lands on a target nobody named.  The old run:device did
+	# exactly that.
+	if [ "$count" -gt 1 ]; then
+		echo "android-deploy: several $TARGET targets are online — name one." >&2
+		printf '%s\n' "$matches" | sed 's/^/    /' >&2
+		echo "    Pass DEVICE_ID=<serial>, or set ANDROID_SERIAL." >&2
+		exit 1
+	fi
+
+	SERIAL="$matches"
+fi
+
+# ---------------------------------------------------------------- #
+# Install
+# ---------------------------------------------------------------- #
+
+echo "android-deploy: $APK ($PKG) -> $SERIAL"
+
+if ! out="$("$ADB" -s "$SERIAL" install -r "$APK" 2>&1)"; then
+	printf '%s\n' "$out"
+	case "$out" in
+	*INSTALL_FAILED_UPDATE_INCOMPATIBLE* | *"signatures do not match"*)
+		cat >&2 <<EOF
+
+The copy of $PKG already installed was signed with a different key, and
+Android never allows that as an update.
+
+The only way forward is an uninstall — **which deletes that app's data**,
+and for this app that is the user's library, irreversibly.  So it is not
+done for you.  If the installed copy is disposable:
+
+    $ADB -s $SERIAL uninstall $PKG
+
+If it is not — if this is a released build with a real library on it —
+install the debug variant instead, which carries applicationIdSuffix
+".dev" and so sits beside it rather than replacing it:
+
+    wails3 task android:assemble:apk
+EOF
+		;;
+	*INSTALL_FAILED_VERSION_DOWNGRADE*)
+		cat >&2 <<EOF
+
+The installed copy of $PKG has a higher versionCode than this build.
+A bare 'make android' builds versionCode 1; a versioned one builds e.g.
+10301.  Either build with a version:
+
+    YJ_VERSION=1.3.1 YJ_VERSION_CODE=10301 make android
+
+or, if the installed copy is disposable, remove it:
+
+    $ADB -s $SERIAL uninstall $PKG
+EOF
+		;;
+	esac
+	exit 1
+fi
+printf '%s\n' "$out"
+
+[ "$LAUNCH" -eq 1 ] || exit 0
+
+"$ADB" -s "$SERIAL" shell am start -n "$PKG/$ACTIVITY"

scripts/android-emulator.sh

@@ -34,7 +34,21 @@ cd "$(dirname "$0")/.."
 
 AVD="${YJ_AVD:-yj-test}"
 SDK="${ANDROID_SDK_ROOT:-${ANDROID_HOME:-$HOME/Android/Sdk}}"
-PKG="${YJ_ANDROID_PKG:-app.yellowjacket}"
+# The third declaration of the app's identity, and the one #159 did not
+# cash out in -- but the same hazard, so it is derived rather than
+# written down too. The APK in bin/ is what `make android-install` is
+# about to install and what `android-launch`, `logs` and `smoke` are
+# about to address, so it is the authority; whatever Gradle resolved the
+# applicationId to, suffix included, is in the file.
+#
+# The literal survives only as the answer for a tree with no APK built
+# yet, where these commands are asking about whatever is already on the
+# device and there is nothing to read. YJ_ANDROID_PKG still overrides.
+PKG="${YJ_ANDROID_PKG:-}"
+if [ -z "$PKG" ] && [ -f bin/yellowjacket.apk ]; then
+	PKG="$(./scripts/android-pkgid.sh bin/yellowjacket.apk 2>/dev/null || true)"
+fi
+PKG="${PKG:-app.yellowjacket}"
 # Where `make android-inspect` forwards the WebView's devtools socket.
 CDP_PORT="${YJ_ANDROID_CDP_PORT:-9222}"
 # **Not "$PKG/.MainActivity".** A leading-dot activity is resolved
@@ -281,15 +295,24 @@ cmd_inspect() {
 	need_sdk
 	pick_device || die "no device -- plug a phone in (USB debugging on) or run 'make android-emulator'"
 
-	local pkg pid
+	local pkg pid candidates
 	pid=""
 
-	for pkg in "$PKG.dev" "$PKG"; do
+	# Debug sibling first, release second, whichever way round $PKG was
+	# resolved -- it is read from the built APK now, so it is already the
+	# .dev id whenever a debug build is what is in bin/, and appending a
+	# second ".dev" to it would probe a package that cannot exist.
+	case "$PKG" in
+	*.dev) candidates="$PKG ${PKG%.dev}" ;;
+	*) candidates="$PKG.dev $PKG" ;;
+	esac
+
+	for pkg in $candidates; do
 		pid=$("$ADB" shell pidof "$pkg" 2>/dev/null | tr -d '\r' | awk '{print $1}')
 		[ -n "$pid" ] && break
 	done
 
-	[ -n "$pid" ] || die "neither $PKG.dev nor $PKG is running; launch it first"
+	[ -n "$pid" ] || die "none of: $candidates is running; launch it first"
 
 	"$ADB" forward --remove-all >/dev/null 2>&1 || true
 	"$ADB" forward "tcp:$CDP_PORT" "localabstract:webview_devtools_remote_$pid" >/dev/null \

scripts/android-pkgid.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+#
+# Print the package id an APK actually declares — and, given --expect,
+# refuse when that is not the id the caller was about to act on.
+#
+# This exists because the identity is declared twice and nothing made
+# the two agree.  `applicationId` in build/android/app/build.gradle is
+# what Gradle installs; `APP_ID` in build/android/Taskfile.yml was what
+# every adb-driven task uninstalled, launched and filtered.  They differ
+# for a reason nobody has to get wrong: the debug buildType carries
+# `applicationIdSuffix ".dev"`, so a debug build is app.yellowjacket.dev
+# while the default was app.yellowjacket — the *release* id, and on a
+# real phone the released app with the user's library on it (#159).
+#
+# So the id is read back from the artifact rather than written down a
+# third time.  The APK is the authority because the task that installs
+# it has just built it: whatever Gradle resolved the applicationId to,
+# suffixes and flavours included, is in the file, and no default can
+# disagree with it.
+#
+# Usage:
+#   android-pkgid.sh <apk> [--expect <id>]
+#
+# Exit codes: 0 printed the id; 1 could not read it; 2 --expect failed.
+set -euo pipefail
+
+die() { echo "android-pkgid: $*" >&2; exit 1; }
+
+APK=""
+EXPECT=""
+while [ $# -gt 0 ]; do
+	case "$1" in
+	--expect) EXPECT="${2:-}"; shift 2 ;;
+	-*) die "unknown option $1" ;;
+	*) APK="$1"; shift ;;
+	esac
+done
+
+[ -n "$APK" ] || die "usage: android-pkgid.sh <apk> [--expect <id>]"
+[ -f "$APK" ] || die "no such APK: $APK"
+
+# aapt2 lives under build-tools/<version>/, which is versioned, so it is
+# resolved rather than pinned.  PATH first, so a system aapt2 (Arch ships
+# one) works without an SDK layout at all.
+find_aapt() {
+	local sdk name
+	for name in "$@"; do
+		command -v "$name" 2>/dev/null && return 0
+	done
+	sdk="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$HOME/Android/Sdk}}"
+	for name in "$@"; do
+		ls "$sdk"/build-tools/*/"$name" 2>/dev/null | sort -V | tail -1 | grep . && return 0
+	done
+	return 1
+}
+
+pkg=""
+
+# `aapt2 dump packagename` answers in one word and is the cheapest of
+# the three.  aapt1 is the fallback because it is what older build-tools
+# carry and what the issue's own measurement used.
+if AAPT2="$(find_aapt aapt2)"; then
+	pkg="$("$AAPT2" dump packagename "$APK" 2>/dev/null | head -1 | tr -d '\r')" || true
+fi
+
+if [ -z "$pkg" ] && AAPT="$(find_aapt aapt)"; then
+	pkg="$("$AAPT" dump badging "$APK" 2>/dev/null |
+		sed -n "s/^package: name='\([^']*\)'.*/\1/p" | head -1)" || true
+fi
+
+# Guessing here is the bug this file exists to prevent, so an unreadable
+# APK is a hard failure and never a fallback to a written-down default.
+if [ -z "$pkg" ]; then
+	die "could not read a package name from $APK.
+    Install the SDK build-tools (aapt2), or set ANDROID_HOME to an SDK
+    that carries them:  sdkmanager 'build-tools;34.0.0'"
+fi
+
+if [ -n "$EXPECT" ] && [ "$EXPECT" != "$pkg" ]; then
+	cat >&2 <<EOF
+android-pkgid: refusing to act on a package this APK does not declare.
+
+    the APK declares:  $pkg
+    the task expects:  $EXPECT
+    APK:               $APK
+
+These must agree, and when they do not it is the *expectation* that is
+wrong: the APK is what Gradle built.  A debug build carries
+applicationIdSuffix ".dev" (app/build.gradle), so a task that assembles
+a debug APK and then addresses the unsuffixed id is addressing the
+released app — which on a real device is the user's install, with their
+library in it (#159).
+EOF
+	exit 2
+fi
+
+printf '%s\n' "$pkg"