Merge pull request 'Main builds and bundles its own signed APK, so a merge ships the app without a release (#6465 )' (#157 ) from dev into main

ci: main builds and bundles its own signed APK, so a merge ships the app without a release (#6465 )
android-release now runs on main as well as dev and tags, and image-release requires its success on every ref. :latest carries the stable APK built from main's own commit instead of the newest release's, so a merged app change reaches stable phones on the next pull. Releases stay as optional bookmarks that attach the APK for download. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 13:22:20 -04:00 · 2026-10-26 12:49:39 -04:00 · 2026-10-26 12:32:32 -04:00 · 2026-10-26 11:20:17 -04:00 · 2026-10-26 10:08:02 -04:00 · 2026-10-08 22:30:10 -04:00
6 changed files with 246 additions and 208 deletions
@@ -2,9 +2,9 @@ name: release

 # Builds and pushes the minstrel container image to the Gitea registry.
 #
-#   push to dev                  → :dev            (freshly-built dev APK bundled)
-#   push to main                 → :latest + :<sha> (latest-release APK bundled)
-#   push tag vYYYY.MM.DD.HHMM    → :latest          (fresh APK bundled)
+#   push to dev                  → :dev             (freshly-built dev APK bundled)
+#   push to main                 → :latest + :<sha> (freshly-built stable APK bundled)
+#   push tag vYYYY.MM.DD.HHMM    → :latest          (fresh APK bundled, and attached to the Release)
 #   workflow_dispatch            → manual trigger (same rules based on the ref)
 #
 # That is the whole tag map.
@@ -41,6 +41,12 @@ name: release
 # image in the same run from the same commit, and the channel cannot go
 # stale against its own artifact.
 #
+# Every branch build carries the app built from its own commit, so a merge to
+# main is all it takes to put a new app in front of stable phones: `:latest`
+# serves it from /api/client/apk and the in-app update offers it. A release
+# is an optional bookmark — a named point in history with the APK attached
+# for download — never a step the app has to wait for.
+#
 # Release model: the tag IS the artifact's version name with a `v` in front.
 # `v2026.09.10.1432` and `2026.09.10.1432` are the same string, derived from
 # the tagged commit's UTC timestamp — so there is no mismatch to reconcile
@@ -56,20 +62,14 @@ name: release
 # :latest is updated by every main push AND every tag push, so it always
 # reflects the newest blessed image.
 #
-# APK pipeline: on tag pushes the android-release job builds + signs the
-# Android APK and uploads it as a workflow artifact. The image-release
-# job declares `needs: android-release`, so the docker image cannot
-# start building until the APK is guaranteed-ready — no polling, no
-# race, no silent-failure mode. Attaching the APK to the gitea Release is
-# its own job (release-assets), behind the test gate below.
-#
-# :latest always carries an APK. Because every main push also moves
-# :latest (not just tags), a main build with no APK would silently strip
-# the in-app update channel off :latest until the next release. So on
-# non-tag builds image-release pulls the MOST RECENT release's signed APK
-# AND the version sidecar published beside it — the recorded values, not
-# recomputed ones — so no rebuild is needed, just a rebundle. Tag builds
-# keep bundling their own freshly-built APK.
+# APK pipeline: on every push — dev, main and tags alike — the
+# android-release job builds + signs the Android APK and uploads it as a
+# workflow artifact. The image-release job declares `needs: android-release`
+# and requires its success, so the docker image cannot start building until
+# the APK is guaranteed-ready — no polling, no race, no silent-failure mode,
+# and no image that moves a channel without an app inside it. Attaching the
+# APK to the gitea Release is its own job (release-assets), tags only, behind
+# the test gate below.
 #
 # THE GATE. Every verifying lane lives in this file —
 # Go (vet, lint, short tests), the Postgres integration suite, the web app
@@ -400,11 +400,14 @@ jobs:
  # ------------------------------------------------------------ artifacts --

  android-release:
-    name: Build signed APK (releases and dev)
-    # Also builds on `dev`, which is what makes a test channel possible at
-    # all: without it the only way to get a build onto a phone is to cut a
-    # release, which quietly turns `main` into the staging area.
-    if: startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/dev'
+    name: Build signed APK
+    # Builds on every ref, so each channel's image carries the app from its
+    # own commit: `dev` for the test channel, `main` for stable phones, and a
+    # tag for the copy attached to its Release.
+    if: >-
+      startsWith(github.ref, 'refs/tags/v')
+      || github.ref == 'refs/heads/dev'
+      || github.ref == 'refs/heads/main'
    runs-on: flutter-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-android:36
@@ -452,7 +455,7 @@ jobs:
          # The derivation lives in ci/version.sh, not here, so it can be
          # executed by a test on every push. Anything inline in this file is
          # unverifiable until a release is already running.
-          out="$(ci/version.sh HEAD)"
+          out="$(ci/version.sh --apk HEAD)"
          printf '%s\n' "${out}" >> "$GITHUB_OUTPUT"

          # The channel is a property of the LANE, not of the commit, which is
@@ -601,9 +604,9 @@ jobs:
          path: release-apk/

      - name: Attach APK to gitea Release
-        # Tag releases only. A dev build has no Release to hang assets on and
-        # does not need one — the :dev image bundles the APK, and the server
-        # serves it from /api/client/apk like any other.
+        # Tag releases only. A branch build has no Release to hang assets on
+        # and does not need one — its image bundles the APK, and the server
+        # serves it from /api/client/apk.
        shell: bash
        env:
          CI_TOKEN: ${{ secrets.CI_TOKEN }}
@@ -667,10 +670,9 @@ jobs:

  image-release:
    name: Build + push container image
-    # Every lane must have SUCCEEDED, each named here. Then the
-    # APK: tag and dev pushes build one and it must have succeeded; main
-    # pushes skip android-release and bundle the latest release's APK
-    # instead, so for main alone a skipped android-release is expected.
+    # Every lane must have SUCCEEDED, each named here, and so must the APK
+    # build: every ref bundles the APK built from its own commit, so an
+    # image without one would move a channel with no app for phones to take.
    needs: [go, integration, web, android, govulncheck, android-release]
    if: >-
      ${{
@@ -680,8 +682,7 @@ jobs:
      && needs.web.result == 'success'
      && needs.android.result == 'success'
      && needs.govulncheck.result == 'success'
-      && (needs.android-release.result == 'success'
-      || (needs.android-release.result == 'skipped' && github.ref == 'refs/heads/main')) }}
+      && needs.android-release.result == 'success' }}
    runs-on: go-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-go:1.26
@@ -747,9 +748,10 @@ jobs:
            # publish the moving channel tag and never a commit-addressable
            # one.
            #
-            # :latest must move here rather than waiting for the next main
-            # push, or the channel would carry the PREVIOUS release's APK
-            # indefinitely — a channel that cannot refresh itself.
+            # :latest moves here so the server hands out the same APK build
+            # that is attached to the Release: a phone that installed from the
+            # Release page and one that updated in-app hold one build, with one
+            # ordering key. Cut a release on main's tip, as :latest follows it.
            CHANNEL=stable
            echo "args=-t ${IMAGE}:latest" >> "$GITHUB_OUTPUT"
            echo "::notice::Release build ${VERSION}: refreshing :latest around the new APK"
@@ -782,12 +784,8 @@ jobs:
            | docker login git.fabledsword.com -u "${{ github.actor }}" --password-stdin

      - name: Download signed APK artifact
-        # Tag and dev pushes — android-release just produced this. Only `main`
-        # takes the "Bundle latest release APK" path below, because it is the
-        # one ref that moves a channel without building an APK of its own.
-        if: >-
-          steps.guard.outputs.ready == 'true' &&
-          (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/dev')
+        # android-release just produced this, on every ref.
+        if: steps.guard.outputs.ready == 'true'
        # Consuming half of the pair: stock download-artifact, which works here for
        # the same reason as the upload (gitea/runner 3.x edits the GHES refusal
        # out of the bundle). v8 runs on node24, which every CI-runner image
@@ -798,9 +796,7 @@ jobs:
          path: client/

      - name: Stage bundled APK + version sidecar
-        if: >-
-          steps.guard.outputs.ready == 'true' &&
-          (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/dev')
+        if: steps.guard.outputs.ready == 'true'
        shell: bash
        env:
          # All three pulled from android-release's outputs so the sidecar the
@@ -821,65 +817,6 @@ jobs:
          cat client/minstrel.apk.version
          ls -lh client/

-      - name: Bundle latest release APK (non-tag :latest builds)
-        # Main pushes don't build an APK, but they DO move :latest — so
-        # without this the in-app update channel would vanish from :latest
-        # until the next tag. Pull the most-recent release's signed APK and
-        # the sidecar published beside it, so what the server reports is what
-        # that build actually recorded rather than something re-derived here.
-        # Degrades to an empty client/ (404 update channel) — never a wrong
-        # version — if no release or APK asset can be resolved. That
-        # degradation only actually works because the greps below carry
-        # `|| true`; under the runner's default pipefail a non-matching grep
-        # kills the step instead of falling through to the empty-case branch.
-        if: steps.guard.outputs.ready == 'true' && github.ref == 'refs/heads/main'
-        shell: bash
-        env:
-          CI_TOKEN: ${{ secrets.CI_TOKEN }}
-        run: |
-          set -eu
-          REPO="${GITHUB_REPOSITORY}"
-          REL_JSON="$(curl -fsSL -H "Authorization: token ${CI_TOKEN}" \
-            "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/latest" || true)"
-          if [ -z "${REL_JSON}" ]; then
-            echo "::notice::no published release — image ships without bundled APK"; exit 0
-          fi
-          # `|| true` on every one of these, and it is load-bearing rather
-          # than defensive habit. The runner already invokes this shell as
-          # `bash -e -o pipefail`, so a pipeline whose grep matches NOTHING
-          # exits non-zero even though `head` succeeded — and the step dies at
-          # the assignment, before ever reaching the `if` written to handle the
-          # empty case. Every "degrades gracefully" branch below is unreachable
-          # without this.
-          TAG="$(printf '%s' "${REL_JSON}" | grep -oP '"tag_name":\s*"\K[^"]+' | head -1)" || true
-          APK_URL="$(printf '%s' "${REL_JSON}" | grep -oP '"browser_download_url":\s*"\K[^"]+' | grep -E '\.apk$' | head -1)" || true
-          if [ -z "${TAG}" ] || [ -z "${APK_URL}" ]; then
-            echo "::notice::latest release '${TAG:-?}' has no APK asset — image ships without bundled APK"; exit 0
-          fi
-          curl -fsSL -H "Authorization: token ${CI_TOKEN}" -o client/minstrel.apk "${APK_URL}"
-
-          # Take the version the release RECORDED rather than recomputing it.
-          # Re-deriving it from the tagged commit would keep the formula in two
-          # files that must stay in step, and could only ever recover the name —
-          # the ordering key is build-time minutes and exists nowhere after that
-          # build ends.
-          SIDECAR_URL="$(printf '%s' "${REL_JSON}" | grep -oP '"browser_download_url":\s*"\K[^"]+' | grep -E '\.apk\.version$' | head -1)" || true
-          if [ -n "${SIDECAR_URL}" ]; then
-            curl -fsSL -H "Authorization: token ${CI_TOKEN}" -o client/minstrel.apk.version "${SIDECAR_URL}"
-            cat client/minstrel.apk.version
-          else
-            # Releases published before sidecars were attached. Their name is
-            # still recoverable from the tag, but their ordering key genuinely
-            # is not — so it is reported ABSENT rather than guessed. A wrong
-            # key is an install the platform refuses; an absent one just tells
-            # the client to fall back to comparing names, which is exactly
-            # what those builds already do.
-            echo "::notice::release ${TAG} predates the version sidecar — bundling with name only, no ordering key"
-            printf '{"name":"%s","code":null,"channel":"stable"}\n' "${TAG#v}" > client/minstrel.apk.version
-          fi
-          echo "::notice::bundled release APK from ${TAG}"
-          ls -lh client/
-
      - name: Build and push
        if: steps.guard.outputs.ready == 'true'
        # --pull: the Dockerfile's base images are floating tags (golang:1.26,
@@ -216,24 +216,56 @@ class MinstrelForwardingPlayer(
    // drops via isLoadingUpnp() = true; the OutputPickerController
    // observes the uiState.queue change and runs the resync (re-clears
    // Sonos's native queue + AddURIToQueue the new tracks + Play).
+    //
+    // The SAME tracks set again (play on the album already queued, from
+    // another track) is not a new queue: the renderer already holds it, and
+    // the uiState collector -- which keys on the track ids -- would never see
+    // a change to resync on, leaving the cast stuck "loading". It is a move
+    // within the queue, so the renderer is pointed at the new track and the
+    // play() that follows goes through.

    override fun setMediaItems(mediaItems: List<MediaItem>) {
+        val sameQueue = holdsSameItems(mediaItems)
        super.setMediaItems(mediaItems)
-        markPendingResyncIfRemote()
+        afterQueueSet(sameQueue)
    }

    override fun setMediaItems(mediaItems: List<MediaItem>, resetPosition: Boolean) {
+        val sameQueue = holdsSameItems(mediaItems)
        super.setMediaItems(mediaItems, resetPosition)
-        markPendingResyncIfRemote()
+        afterQueueSet(sameQueue)
    }

    override fun setMediaItems(mediaItems: List<MediaItem>, startIndex: Int, startPositionMs: Long) {
+        val sameQueue = holdsSameItems(mediaItems)
        super.setMediaItems(mediaItems, startIndex, startPositionMs)
-        markPendingResyncIfRemote()
+        afterQueueSet(sameQueue)
    }

-    private fun markPendingResyncIfRemote() {
-        val wasActive = holder.active.value ?: return
+    private fun holdsSameItems(mediaItems: List<MediaItem>): Boolean =
+        mediaItems.size == delegate.mediaItemCount &&
+            mediaItems.indices.all { mediaItems[it].mediaId == delegate.getMediaItemAt(it).mediaId }
+
+    private fun afterQueueSet(sameQueue: Boolean) {
+        val active = holder.active.value ?: return
+        if (!sameQueue) {
+            markPendingResync(active)
+            return
+        }
+        val index = delegate.currentMediaItemIndex
+        val positionMs = delegate.currentPosition.coerceAtLeast(0L)
+        Timber.w(
+            "setMediaItems with the queue %s already holds -- moving to track %d",
+            active.routeName,
+            index + 1,
+        )
+        when (active.queueMode) {
+            QueueMode.SINGLE_TRACK -> startSingleTrack(active, index, positionMs)
+            QueueMode.NATIVE_QUEUE -> seekNativeQueue(active, index, positionMs)
+        }
+    }
+
+    private fun markPendingResync(wasActive: ActiveUpnp) {
        Timber.w(
            "setMediaItems while UPnP active (%s) -- marking pending resync",
            wasActive.routeName,
@@ -332,11 +364,15 @@ class MinstrelForwardingPlayer(
        super.seekTo(mediaItemIndex, positionMs)
        when (active.queueMode) {
            QueueMode.SINGLE_TRACK -> playSingleTrackAt(active, mediaItemIndex, positionMs)
-            QueueMode.NATIVE_QUEUE -> sendNativeQueueCommand(active) {
-                active.avTransport.seekToTrack(mediaItemIndex + 1)
-                if (positionMs > 0L) {
-                    active.avTransport.seek(positionMs)
-                }
+            QueueMode.NATIVE_QUEUE -> seekNativeQueue(active, mediaItemIndex, positionMs)
+        }
+    }
+
+    private fun seekNativeQueue(active: ActiveUpnp, index: Int, positionMs: Long) {
+        sendNativeQueueCommand(active) {
+            active.avTransport.seekToTrack(index + 1)
+            if (positionMs > 0L) {
+                active.avTransport.seek(positionMs)
            }
        }
    }
@@ -383,23 +383,27 @@ class OutputPickerController @Inject constructor(
            resyncSingleTrack(upnpRoute, transport, newQueue, newCurrentIndex)
            return@withLock
        }
-        val handledIncrementally = runCatching {
+        // The incremental diff is for a queue changed under a cast that kept
+        // running (play next, an append, a removal): it leaves the playing
+        // track alone. A queue REPLACED through setMediaItems has already
+        // cleared active, and the listener asked for its start track and for
+        // it to play -- both of which the diff would ignore, and with active
+        // never restored the app would think it had gone back to the phone
+        // while the speaker played on. That case reloads in full below.
+        val stillActive = activeUpnpHolder.active.value?.routeId == routeId
+        val handledIncrementally = stillActive && runCatching {
            sonosQueue.tryIncrementalResync(transport, oldIds, newQueue)
        }.getOrElse { e ->
            Timber.w(e, "Sonos incremental resync errored; falling back to full reload")
            false
        }
        if (handledIncrementally) {
-            // Active was never cleared on the incremental path; clear any
-            // target that markPendingResyncIfRemote set (it didn't, for
-            // incremental cases that don't go through setMediaItems, but
-            // belt-and-suspenders).
            activeUpnpHolder.setTarget(null)
            return@withLock
        }
        // Full rebuild: ensure active is cleared so transport calls drop
-        // (markPendingResyncIfRemote may already have done this on the
-        // setMediaItems path).
+        // (the forwarding player has already done this on the setMediaItems
+        // path).
        if (activeUpnpHolder.active.value != null) {
            activeUpnpHolder.set(null)
            activeUpnpHolder.setTarget(routeId)
@@ -62,7 +62,7 @@ class UpdateRepository(
    private val installedCode: Long,
    private val installedName: String,
    private val offers: Boolean,
-    // Where the updater before this one kept its download, never cleaned up.
+    // A download left by older builds of the app, which nothing else removes.
    private val legacyApk: File? = null,
 ) {
    private val turns = Mutex()
@@ -3,11 +3,17 @@
 # Derives the three values a build is stamped with, and the tag that names it.
 #
 #   name=YYYY.MM.DD.HHMM   label for people, from the timestamp of the newest
-#                          commit that CHANGED SOMETHING SHIPPED (see SHIPPED)
+#                          commit that CHANGED SOMETHING SHIPPED (see SHIPPED,
+#                          or SHIPPED_APK with --apk)
 #   code=<int>             ordering key, minutes since 2020-01-01 at BUILD time
 #   tag=v<name>            what a release of this commit must be called
 #
-# Usage:  ci/version.sh [<commit-ish>]        (default HEAD)
+# Usage:  ci/version.sh [--apk] [<commit-ish>]        (default HEAD)
+#
+#   --apk  names the Android app from android/ alone. The app compares this
+#          name with the one it is running, and a different name is what
+#          offers an update — so a name that moved for a server-only commit
+#          would offer every phone a rebuild of the app it already has.
 #
 # This exists as a script rather than inline workflow YAML for one reason:
 # release.yml only runs on `main` and on tags, so anything living inside it is
@@ -30,6 +36,12 @@
 set -euo pipefail

 readonly EPOCH_2020=1577836800 # 2020-01-01T00:00:00Z
+
+apk=false
+if [ "${1:-}" = "--apk" ]; then
+  apk=true
+  shift
+fi
 readonly REF="${1:-HEAD}"

 # Both clocks are overridable so a test can pin them. Nothing but tests should
@@ -48,14 +60,17 @@ readonly REF="${1:-HEAD}"
 #   wrongly included → version moves when nothing shipped. Cosmetic noise in
 #                      a string nobody sorts.
 #
-# THIS REPO SHIPS TWO ARTIFACTS FROM ONE DERIVATION, and that is why the list
-# is shorter than it looks like it should be. The server image ships cmd/,
-# internal/, shared/, web/, config.example.yaml and client/; the APK ships
-# android/. Neither ships the other's sources — but excluding android/ here
-# would stop an Android-only commit from moving the APK's OWN version, which
-# is the dangerous direction. So this is the union: exclude only what ships in
-# NEITHER, and accept that an Android commit also nudges the server's reported
-# version. Over-inclusion across the two, which is the harmless direction.
+# THIS LIST NAMES THE SERVER IMAGE, and it is shorter than it looks like it
+# should be. The image ships cmd/, internal/, shared/, web/,
+# config.example.yaml and client/ — and client/ holds the APK, so android/
+# stays in: an Android-only commit changes what the image carries. Exclude
+# only what ships in neither artifact; over-inclusion is the harmless
+# direction here.
+#
+# The APK itself is named from SHIPPED_APK (below), where over-inclusion is
+# NOT harmless: the app offers an update whenever the name differs from its
+# own, so a name moved by a server-only commit offers every phone a rebuild
+# of the app it already has.
 #
 # The family's other repos (roundtable / roundtable-android) each keep a
 # tighter list because they are separate repos with one artifact apiece. Do
@@ -100,9 +115,24 @@ readonly SHIPPED=(
  ':!web/vitest.setup.ts'
 )

+# What the APK is built from: android/ and nothing else (the Gradle build
+# reads no path outside it). Still a denylist within it, for the same reason
+# as above — a new directory under android/ counts until named here.
+readonly SHIPPED_APK=(
+  android
+  ':!android/app/src/test'        # JVM unit tests
+  ':!android/*.md'
+)
+
+if [ "${apk}" = true ]; then
+  shipped=("${SHIPPED_APK[@]}")
+else
+  shipped=("${SHIPPED[@]}")
+fi
+
 commit_epoch="${MINSTREL_COMMIT_EPOCH:-}"
 if [ -z "${commit_epoch}" ]; then
-  commit_epoch="$(git log --format=%ct -1 "${REF}" -- "${SHIPPED[@]}")"
+  commit_epoch="$(git log --format=%ct -1 "${REF}" -- "${shipped[@]}")"
  # Loudly, on purpose. A silent fallback here is the landmine this whole
  # script exists to avoid: a plausible-looking version that is quietly wrong,
  # on a green run. Realistically this means a shallow clone (no commit in
@@ -272,73 +272,41 @@ func TestDevChannel_PublishesDevAloneAndNeverLatest(t *testing.T) {
 	}
 }

-// The two bundling paths must stay mutually exclusive. If the rebundle step's
-// condition were relaxed back to "not a tag", a dev push would run BOTH: stage
-// its freshly-built APK, then overwrite it with the previous release's. The
-// image would still build and the sidecar would still parse — it would just
-// quietly serve stale art to the channel whose whole job is being current.
-func TestDevChannel_RebundlePathIsMainOnly(t *testing.T) {
-	body, err := os.ReadFile(filepath.Join(repoRoot(t), ".gitea", "workflows", "release.yml"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	yaml := string(body)
+// A merge to main is enough to put a new app in front of stable phones: main
+// builds the signed APK from its own commit and bakes it into :latest, as dev
+// does for :dev. The regression to guard is main falling back to a tag-only
+// APK build, which leaves every merged app change waiting on a release while
+// each build stays green.
+func TestEveryBranchShipsTheAppBuiltFromItsOwnCommit(t *testing.T) {
+	jobs := releaseJobs(t)

-	i := strings.Index(yaml, "- name: Bundle latest release APK")
-	if i < 0 {
-		t.Fatal("no 'Bundle latest release APK' step")
-	}
-	step := yaml[i:]
-	if j := strings.Index(step, "\n      - name:"); j >= 0 {
-		step = step[:j]
-	}
-	if !strings.Contains(step, "github.ref == 'refs/heads/main'") {
-		t.Errorf("the rebundle step is not gated to main; a dev push would overwrite its own APK\n%s", step)
-	}
-}
-
-// The runner invokes `shell: bash` as `bash -e -o pipefail`. That makes any
-// command substitution whose grep matches NOTHING fatal at the assignment —
-// pipefail reports the grep's non-zero status even though `head` succeeded —
-// so the step dies before reaching the `if` written to handle the empty case.
-//
-// This is not hypothetical. It took down the first `main` build after the
-// version rework: the newest release predated sidecar assets, its
-// `.apk.version` grep matched nothing, and the step aborted instead of
-// falling through to the name-only branch that exists precisely for it. The
-// same latent hazard sat on the other two assignments and had simply never
-// fired, because their greps always matched.
-//
-// Pins the property that makes every "degrades gracefully" branch in that
-// step reachable at all.
-func TestBundleStep_GrepsCannotKillTheStep(t *testing.T) {
-	body, err := os.ReadFile(filepath.Join(repoRoot(t), ".gitea", "workflows", "release.yml"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	yaml := string(body)
-
-	i := strings.Index(yaml, "- name: Bundle latest release APK")
-	if i < 0 {
-		t.Fatal("no 'Bundle latest release APK' step")
-	}
-	step := yaml[i:]
-	if j := strings.Index(step, "\n      - name:"); j >= 0 {
-		step = step[:j]
-	}
-
-	for _, line := range strings.Split(step, "\n") {
-		trimmed := strings.TrimSpace(line)
-		if strings.HasPrefix(trimmed, "#") || !strings.Contains(trimmed, "grep") {
-			continue
+	build := strings.Join(strings.Fields(jobs["android-release"].If), " ")
+	for _, ref := range []string{"refs/heads/main", "refs/heads/dev", "refs/tags/v"} {
+		if !strings.Contains(build, ref) {
+			t.Errorf("android-release does not build on %s, so that ref's image carries no app of its own\n  if: %s", ref, build)
 		}
-		// Only assignments from a command substitution can abort the step.
-		if !strings.Contains(trimmed, `="$(`) {
-			continue
-		}
-		if !strings.HasSuffix(trimmed, "|| true") {
-			t.Errorf("this assignment dies under pipefail when its grep matches nothing, "+
-				"skipping the empty-case branch below it:\n  %s", trimmed)
+	}
+
+	image := strings.Join(strings.Fields(jobs["image-release"].If), " ")
+	if !strings.Contains(image, "needs.android-release.result == 'success'") || strings.Contains(image, "'skipped'") {
+		t.Errorf("image-release can publish without a freshly-built APK\n  if: %s", image)
+	}
+
+	yaml := releaseYAML(t)
+	if strings.Contains(yaml, "releases/latest") {
+		t.Error("release.yml fetches the latest release; an image bundling a release's APK ships an app older than its own commit")
+	}
+
+	// Both bundling steps run on every ref. Sliced from image-release on,
+	// because release-assets has a step of the same name.
+	i := strings.Index(yaml, "\n  image-release:")
+	if i < 0 {
+		t.Fatal("no image-release job")
+	}
+	for _, name := range []string{"Download signed APK artifact", "Stage bundled APK + version sidecar"} {
+		step := stepBody(t, yaml[i:], name)
+		if strings.Contains(step, "github.ref") {
+			t.Errorf("%q is gated by ref, so some ref's image ships without its APK\n%s", name, step)
 		}
 	}
 }
@@ -376,7 +344,7 @@ func TestReleaseBuild_RefreshesTheChannelAndMintsNothingElse(t *testing.T) {
 	arm, _, _ := imageTagArms(t, releaseYAML(t))

 	if !strings.Contains(arm, "${IMAGE}:latest") {
-		t.Errorf("tag arm does not refresh :latest — the channel would keep serving the PREVIOUS release's APK until someone pushed to main\n%s", arm)
+		t.Errorf("tag arm does not refresh :latest — the server would hand out a different APK build from the one attached to the Release\n%s", arm)
 	}
 	if strings.Contains(arm, "GITHUB_SHA") {
 		t.Errorf("tag arm mints a :<sha> image; that would re-push main's immutable rollback target with different bundled contents\n%s", arm)
@@ -455,7 +423,7 @@ func TestImageBuild_StampsADerivedVersionAndAChannel(t *testing.T) {
 		t.Errorf("the main arm stamps the literal string \"main\" as a version; two images months apart would be indistinguishable\n%s", mainArm)
 	}
 	if !strings.Contains(yaml, "ci/version.sh HEAD | sed") {
-		t.Error("the image job no longer derives its version from ci/version.sh — the version and the APK's version can now drift apart")
+		t.Error("the image job no longer derives its version from ci/version.sh — the image's version has drifted out of test coverage")
 	}
 }

@@ -508,10 +476,11 @@ func commitFile(t *testing.T, dir, path, epoch string) {
 }

 // versionIn runs ci/version.sh inside dir, reading real git rather than the
-// pinned-clock override, so the PATHSPEC is what is under test.
-func versionIn(t *testing.T, dir string) (string, error) {
+// pinned-clock override, so the PATHSPEC is what is under test. flags go
+// before the ref, as in `--apk`.
+func versionIn(t *testing.T, dir string, flags ...string) (string, error) {
 	t.Helper()
-	cmd := exec.Command(filepath.Join(repoRoot(t), "ci", "version.sh"), "HEAD")
+	cmd := exec.Command(filepath.Join(repoRoot(t), "ci", "version.sh"), append(flags, "HEAD")...)
 	cmd.Dir = dir
 	cmd.Env = append(os.Environ(),
 		"GIT_CONFIG_GLOBAL=/dev/null", "GIT_CONFIG_SYSTEM=/dev/null",
@@ -558,11 +527,9 @@ func TestVersionName_IgnoresCommitsThatShipNothing(t *testing.T) {
 	}
 }

-// android/ is deliberately NOT excluded, and that is the subtle half of the
-// list. It ships in no server image — but it is the APK's entire source, and
-// ONE script derives the version for both artifacts. Excluding it would stop
-// an Android-only commit from moving the APK's own version, which is exactly
-// the silent downgrade the versioning rework exists to prevent.
+// android/ is deliberately NOT excluded from the image's name: the image
+// bundles the APK under client/, so an Android-only commit changes what the
+// image carries, and an image that changed must not keep its old name.
 func TestVersionName_AndroidSourcesCount(t *testing.T) {
 	dir := gitRepo(t)
 	commitFile(t, dir, "internal/server/thing.go", "1757443736")
@@ -573,7 +540,71 @@ func TestVersionName_AndroidSourcesCount(t *testing.T) {
 		t.Fatalf("version.sh failed: %v\n%s", err, out)
 	}
 	if !strings.Contains(out, "name=2026.09.10.0042") {
-		t.Errorf("an Android commit did not move the version; the APK would ship new code under its old version name\n%s", out)
+		t.Errorf("an Android commit did not move the image's version; it carries a new APK under its old name\n%s", out)
+	}
+}
+
+// The app offers an update whenever the server's APK has a different name
+// from its own, so the APK's name must move for Android commits and ONLY for
+// them. A name taken from the whole repo would offer every phone a rebuild of
+// the app it already has on each server-only deploy.
+func TestApkName_MovesOnlyForAndroidCommits(t *testing.T) {
+	const (
+		app    = "1757443736" // 2025.09.09.1848
+		server = "1789000920" // 2026.09.10.0042, later
+		again  = "1789600000" // 2026.09.16.2306, later still
+	)
+	dir := gitRepo(t)
+	commitFile(t, dir, "android/app/src/main/Thing.kt", app)
+	commitFile(t, dir, "internal/server/thing.go", server)
+	commitFile(t, dir, "web/src/routes/page.svelte", server)
+
+	out, err := versionIn(t, dir, "--apk")
+	if err != nil {
+		t.Fatalf("version.sh --apk failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "name=2025.09.09.1848") {
+		t.Errorf("a server-only commit moved the APK's name; every phone would be offered the app it already has\n%s", out)
+	}
+	// The image's name still follows the server commit, so the test above
+	// is not passing because the flag is ignored and everything is stale.
+	out, err = versionIn(t, dir)
+	if err != nil {
+		t.Fatalf("version.sh failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "name=2026.09.10.0042") {
+		t.Errorf("without --apk the name should follow the server commit\n%s", out)
+	}
+
+	// A test-only Android commit ships nothing either.
+	commitFile(t, dir, "android/app/src/test/java/A.kt", again)
+	out, err = versionIn(t, dir, "--apk")
+	if err != nil {
+		t.Fatalf("version.sh --apk failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "name=2025.09.09.1848") {
+		t.Errorf("an Android test-only commit moved the APK's name\n%s", out)
+	}
+
+	// ...and a real Android commit must move it, or new app code would ship
+	// under the name of the old and never be offered.
+	commitFile(t, dir, "android/app/src/main/Thing.kt", again)
+	out, err = versionIn(t, dir, "--apk")
+	if err != nil {
+		t.Fatalf("version.sh --apk failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(out, "name=2026.09.16.2306") {
+		t.Errorf("an Android commit did not move the APK's name; the new app would never be offered\n%s", out)
+	}
+}
+
+// The APK lane must ask for the APK's name. Without the flag it would still
+// build, sign and publish, and quietly go back to offering an update on every
+// server deploy.
+func TestReleaseWorkflow_NamesTheApkFromAndroidAlone(t *testing.T) {
+	step := stepBody(t, releaseYAML(t), "Compute release version")
+	if !strings.Contains(step, "ci/version.sh --apk HEAD") {
+		t.Errorf("the APK lane does not derive its version with --apk\n%s", step)
 	}
 }