feat(mobile): add worktree-aware debug identities (#2858)

**Category:** improvement **User Impact:** Developers can identify which worktree produced a mobile debug app, keep a bounded set of worktree builds installed side by side, and preserve each worktree app's login and local state while switching branches. **Problem:** Mobile debug builds from every checkout currently appear as the same “Buzz” app and share one application identity, so the running source is ambiguous and one worktree build replaces another. A branch-keyed identity would avoid replacement but create stale installs and fresh app state on every branch switch. **Solution:** Give each linked worktree a stable Debug-only application identity derived from its sanitized directory name. Show the sanitized branch name (or short commit SHA when detached) in the display label, persist generated native overrides for direct IDE builds, and leave Release/Profile identities unchanged. Worktree defaults remain lower precedence than a developer's iOS `AppOverrides.xcconfig`. `just mobile-clean` provides a safe cleanup path for suffixed worktree installs while preserving production Buzz. <details> <summary>File changes</summary> **.github/workflows/ci.yml** Runs the expanded worktree override contract when relevant mobile or native configuration changes. **AGENTS.md** Documents worktree-aware mobile development and cleanup for contributors and agents. **Justfile** Generates overrides before mobile development and Android debug builds, and exposes `just mobile-clean`. **mobile/README.md** Explains stable per-worktree identities, branch/SHA labels, direct IDE usage, cleanup, and Release/Profile guarantees. **mobile/android/.gitignore** Ignores generated worktree properties. **mobile/android/app/build.gradle.kts** Loads and validates generated properties, then applies the application ID suffix and display label to Android Debug only. **mobile/android/app/src/main/AndroidManifest.xml** Resolves the Android app label through an overridable string resource. **mobile/ios/.gitignore** Ignores generated iOS worktree settings. **mobile/ios/Flutter/Debug.xcconfig** Loads generated worktree defaults before developer `AppOverrides`, so personal signing overrides retain precedence. **mobile/ios/Flutter/Release.xcconfig** Pins the production display name and bundle identifier for Release/Profile builds. **mobile/ios/Runner/Info.plist** Resolves the visible iOS app name from build settings. **scripts/mobile-worktree-overrides.sh** Detects linked worktrees, derives a stable directory-keyed identity, sanitizes branch/SHA display context, writes native Debug overrides, and removes stale overrides in the main checkout. **scripts/mobile-worktree-clean.sh** Lists or removes suffixed Buzz worktree installs from booted iOS simulators and connected Android emulators without matching production IDs; supports `--dry-run`. **scripts/test-mobile-worktree-overrides.sh** Covers worktree detection, branch-switch identity stability, detached HEAD fallback, special-character sanitization, iOS override precedence, brace-aware Release/Profile purity, cleanup safety, ignores, and command integration. </details> ## Reproduction steps 1. From a linked worktree, activate the repository toolchain and run `just mobile-dev`. 2. Inspect the running app: its label should be `Buzz (<sanitized-branch>)`, while its application ID suffix is derived from the worktree directory. 3. Switch branches in the same worktree, rerun the override script, and confirm the application ID remains stable while the display label updates. In detached HEAD, confirm the label uses a short SHA. 4. Build Debug from a second worktree and confirm both apps remain installed side by side with independent state. 5. Build from Xcode after setting `AppOverrides.xcconfig` and confirm developer overrides still win over generated worktree defaults. 6. Run `just mobile-clean --dry-run`, then `just mobile-clean`, and confirm suffixed worktree installs are targeted while the production app is preserved. 7. Build Release/Profile and confirm the production name and application identity remain unchanged. 8. Run `scripts/test-mobile-worktree-overrides.sh`, `just mobile-check`, `just mobile-test`, and `just mobile-build-android`. ## Screenshots / demos | iOS — labeled app switcher | iOS — side-by-side installs | | --- | --- | | <img width="360" alt="Buzz worktree label in the iOS app switcher" src="https://github.com/user-attachments/assets/4bcae067-7ce5-4333-bb11-2803c4107663" /> | <img width="360" alt="Buzz production and worktree debug apps installed side by side on iOS" src="https://github.com/user-attachments/assets/08a107b5-fdf2-463a-8a4c-81d41d7bf5e7" /> | | Android — side-by-side installs | Android — labeled app switcher | | --- | --- | | <img width="360" alt="Buzz production and worktree debug apps installed side by side on Android" src="https://github.com/user-attachments/assets/4f5841a1-adae-42da-ae84-47c09ec85fb9" /> | <img width="360" alt="Buzz worktree label in the Android app switcher" src="https://github.com/user-attachments/assets/0546ff51-efcc-4cb6-a4bd-2a3af26cd60f" /> | --------- Signed-off-by: Taylor Ho <taylorkmho@gmail.com> Co-authored-by: npub1223z34hd7vtwc6qj4s7flsxkj644nlre2nthu7lrrmkumhu3xddsrx9r6w <52a228d6edf316ec6812ac3c9fc0d696ab59fc7954d77e7be31eedcddf91335b@buzz.block.builderlab.xyz>
2026-08-18 06:50:31 +02:00 · 2026-07-26 13:47:35 -07:00
parent e6c90bb7c4
commit 1a56b7cc9e
14 changed files with 519 additions and 4 deletions
@@ -59,10 +59,13 @@ jobs:
            mobile:
              - 'mobile/**'
              - 'scripts/mobile-release.sh'
+              - 'scripts/mobile-worktree-overrides.sh'
+              - 'scripts/mobile-worktree-clean.sh'
              - 'scripts/publish-mobile-release-candidate.sh'
              - 'scripts/release-rulesets.sh'
              - 'scripts/test-mobile-release-contract.sh'
              - 'scripts/test-mobile-release-candidate-publisher.sh'
+              - 'scripts/test-mobile-worktree-overrides.sh'
              - '.github/workflows/mobile-release-candidate.yml'
              - '.github/workflows/ci.yml'
      - name: Release workflow source contract
@@ -71,6 +74,8 @@ jobs:
        run: |
          scripts/test-mobile-release-contract.sh
          scripts/test-mobile-release-candidate-publisher.sh
+      - name: Mobile worktree identity contract
+        run: scripts/test-mobile-worktree-overrides.sh

  rust-lint:
    name: Rust Lint
@@ -555,6 +555,15 @@ To run the app locally (starts Docker, relay, iOS simulator automatically):
 just mobile-dev
 ```

+When run from a git worktree, `just mobile-dev` (and `just
+mobile-build-android`) give the debug build a per-worktree app identifier
+(keyed to the worktree directory name) and a branch-labelled app name via
+`scripts/mobile-worktree-overrides.sh`, so builds from multiple worktrees
+install side by side. Release builds are unaffected. `just mobile-clean`
+removes stale worktree-suffixed installs from simulators/emulators. See
+[mobile/README.md](mobile/README.md) for direct Xcode / Android Studio
+usage.
+
 ### Testing Conventions

 - Prefer **widget tests** over unit tests for UI components — test the
@@ -620,11 +620,12 @@ mobile-check:
 mobile-test:
    unset GIT_DIR GIT_WORK_TREE; cd {{mobile_dir}} && flutter test

-# Compile an unsigned Android debug APK
+# Compile an unsigned Android debug APK (worktree-aware debug identity)
 mobile-build-android:
+    ./scripts/mobile-worktree-overrides.sh
    unset GIT_DIR GIT_WORK_TREE; cd {{mobile_dir}} && flutter build apk --debug --no-pub

-# Run the mobile app on iOS simulator
+# Run the mobile app on iOS simulator (worktree-aware debug identity)
 mobile-dev:
    #!/usr/bin/env bash
    set -euo pipefail
@@ -632,10 +633,15 @@ mobile-dev:
        open -a Simulator
        sleep 3
    fi
+    ./scripts/mobile-worktree-overrides.sh
    cd {{mobile_dir}}
    unset GIT_DIR GIT_WORK_TREE
    flutter run

+# Uninstall stale worktree-suffixed Buzz debug installs (production apps kept)
+mobile-clean:
+    ./scripts/mobile-worktree-clean.sh
+
 # ─── Database ─────────────────────────────────────────────────────────────────

 # Apply database migrations
@@ -19,6 +19,40 @@ just mobile-dev
 cd mobile && flutter run
 ```

+### Worktree-aware debug identity
+
+Debug builds produced from a git worktree get a unique app identifier keyed
+to the **worktree directory name** (`com.buzz.buzzMobile.<slug>` on iOS,
+`xyz.block.buzz.mobile.<slug>` on Android) plus a display-only branch label
+in the app name (`Buzz (my-branch)`, or a short SHA when the worktree is
+detached). Because the identifier follows the directory rather than the
+branch, one worktree keeps exactly one installed app — and its login state —
+across branch switches, and builds from multiple worktrees install side by
+side, mirroring the desktop dev experience. Release and profile builds
+always keep the production identity and name.
+
+`just mobile-dev` and `just mobile-build-android` apply this automatically by
+running `scripts/mobile-worktree-overrides.sh`, which writes two gitignored
+files:
+
+- `mobile/ios/Flutter/WorktreeOverrides.xcconfig` (included by Debug builds
+  only; a developer's `AppOverrides.xcconfig` is included after it, so
+  app-specific overrides like a personal `BUNDLE_IDENTIFIER` for device
+  signing always win)
+- `mobile/android/worktree.properties` (read by the debug build type only)
+
+For direct Xcode / Android Studio / `flutter run` development, run
+`./scripts/mobile-worktree-overrides.sh` from the repo root once per branch
+switch to refresh the display label (the install identity never changes);
+the persisted files are then picked up by any subsequent build. In the main
+checkout the script is a no-op that removes stale override files, restoring
+the plain `Buzz` identity.
+
+To remove leftover worktree-suffixed installs from booted iOS simulators and
+connected Android emulators, run `just mobile-clean` (add `--dry-run` via
+`./scripts/mobile-worktree-clean.sh --dry-run` to preview). Production
+installs are never touched.
+
 ## Checks

 ```bash
@@ -6,6 +6,7 @@ gradle-wrapper.jar
 /local.properties
 GeneratedPluginRegistrant.java
 .cxx/
+/worktree.properties

 # Remember to never publicly share your keystore.
 # See https://flutter.dev/to/reference-keystore
@@ -1,3 +1,5 @@
+import java.util.Properties
+
 plugins {
    id("com.android.application")
    id("kotlin-android")
@@ -19,6 +21,31 @@ val uploadSigningValues =
 val missingUploadSigningValues = uploadSigningValues.filterValues { it.isNullOrBlank() }.keys
 val hasUploadSigning = missingUploadSigningValues.isEmpty()

+// Worktree-aware debug identity (gitignored, written by
+// scripts/mobile-worktree-overrides.sh): debug builds from a git worktree get a
+// branch-labelled app name and a unique applicationId suffix so builds from
+// multiple worktrees install side by side. Release builds never read this.
+val worktreePropsFile = rootProject.file("worktree.properties")
+val worktreeProps =
+    Properties().apply {
+        if (worktreePropsFile.isFile) worktreePropsFile.inputStream().use { load(it) }
+    }
+val worktreeLabel = worktreeProps.getProperty("label")?.takeIf { it.isNotBlank() }
+if (worktreeLabel != null && !worktreeLabel.matches(Regex("""[A-Za-z0-9._-]+"""))) {
+    throw GradleException(
+        "worktree.properties label must match [A-Za-z0-9._-]+ (safe for string " +
+            "resources), got: " + worktreeLabel,
+    )
+}
+val worktreeIdSuffix =
+    worktreeProps.getProperty("applicationIdSuffix")?.takeIf { it.isNotBlank() }
+if (worktreeIdSuffix != null && !worktreeIdSuffix.matches(Regex("""\.[a-z][a-z0-9_]*"""))) {
+    throw GradleException(
+        "worktree.properties applicationIdSuffix must match \\.[a-z][a-z0-9_]*, got: " +
+            worktreeIdSuffix,
+    )
+}
+
 // Release signing modes:
 //   - "upload-keystore" (default): sign with the CI-vended upload keystore;
 //     release builds fail loudly when any credential is missing.
@@ -64,6 +91,7 @@ android {
        versionCode = flutter.versionCode
        versionName = flutter.versionName
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+        resValue("string", "app_name", "Buzz")
    }

    signingConfigs {
@@ -78,6 +106,16 @@ android {
    }

    buildTypes {
+        debug {
+            // Only debug builds take the worktree identity; release/profile
+            // keep the production applicationId and label.
+            if (worktreeIdSuffix != null) {
+                applicationIdSuffix = worktreeIdSuffix
+            }
+            if (worktreeLabel != null) {
+                resValue("string", "app_name", "Buzz ($worktreeLabel)")
+            }
+        }
        release {
            if (hasUploadSigning) {
                signingConfig = signingConfigs.getByName("upload")
@@ -2,7 +2,7 @@
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA" />
    <application
-        android:label="Buzz"
+        android:label="@string/app_name"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        <activity
@@ -17,6 +17,7 @@ xcuserdata
 **/.generated/
 Flutter/App.framework
 Flutter/AppOverrides.xcconfig
+Flutter/WorktreeOverrides.xcconfig
 Flutter/Flutter.framework
 Flutter/Flutter.podspec
 Flutter/Generated.xcconfig
@@ -6,4 +6,16 @@
 // `mobile/ios/Flutter/AppOverrides.xcconfig` containing
 // `BUNDLE_IDENTIFIER = your.app.id` (gitignored).
 BUNDLE_IDENTIFIER = com.buzz.buzzMobile
+APP_DISPLAY_NAME = Buzz
+
+// Worktree-aware debug identity (gitignored, written by
+// scripts/mobile-worktree-overrides.sh): a per-worktree bundle identifier
+// and a branch-labelled display name so debug builds from multiple worktrees
+// install side by side. Release and Profile builds never include it.
+#include? "WorktreeOverrides.xcconfig"
+
+// Developer app-specific overrides are included last: xcconfig
+// later-include-wins is per variable, so a personal BUNDLE_IDENTIFIER for
+// device signing beats the worktree default while unset variables still
+// fall through to the worktree values.
 #include? "AppOverrides.xcconfig"
@@ -5,6 +5,7 @@
 // enterprise-signed distribution) override these without patching tracked
 // files by writing `mobile/ios/Flutter/AppOverrides.xcconfig` (gitignored).
 BUNDLE_IDENTIFIER = com.buzz.buzzMobile
+APP_DISPLAY_NAME = Buzz
 CODE_SIGN_STYLE = Automatic
 CODE_SIGN_IDENTITY = iPhone Developer
 #include? "AppOverrides.xcconfig"
@@ -7,7 +7,7 @@
 	<key>CFBundleDevelopmentRegion</key>
 	<string>$(DEVELOPMENT_LANGUAGE)</string>
 	<key>CFBundleDisplayName</key>
-	<string>Buzz</string>
+	<string>$(APP_DISPLAY_NAME)</string>
 	<key>CFBundleExecutable</key>
 	<string>$(EXECUTABLE_NAME)</string>
 	<key>CFBundleIdentifier</key>
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Uninstalls stale worktree-suffixed Buzz debug builds from booted iOS
+# simulators and connected Android devices/emulators. Production installs
+# (com.buzz.buzzMobile / xyz.block.buzz.mobile, no suffix) are never touched:
+# only identifiers with a worktree suffix appended after the production id
+# are matched. Run `just mobile-clean` (or this script directly); pass
+# --dry-run to list what would be removed without uninstalling.
+set -euo pipefail
+
+ios_prefix="com.buzz.buzzMobile."
+android_prefix="xyz.block.buzz.mobile."
+
+dry_run=0
+if [[ "${1:-}" == "--dry-run" ]]; then
+    dry_run=1
+fi
+
+removed=0
+
+# ── iOS: booted simulators only ──────────────────────────────────────────────
+if command -v xcrun &>/dev/null; then
+    booted=$(xcrun simctl list devices booted 2>/dev/null | sed -n 's/.*(\([0-9A-F-]\{36\}\)) (Booted).*/\1/p' || true)
+    for udid in $booted; do
+        # `simctl listapps` emits a plist keyed by bundle id; extract keys
+        # that carry the worktree suffix.
+        bundles=$(xcrun simctl listapps "$udid" 2>/dev/null \
+            | plutil -convert json -o - -- - 2>/dev/null \
+            | python3 -c 'import json,sys; print("\n".join(k for k in json.load(sys.stdin) if k.startswith(sys.argv[1])))' "$ios_prefix" \
+            || true)
+        for bundle in $bundles; do
+            if [[ "$dry_run" == "1" ]]; then
+                echo "would uninstall (iOS $udid): $bundle"
+            else
+                echo "uninstalling (iOS $udid): $bundle"
+                xcrun simctl uninstall "$udid" "$bundle"
+            fi
+            removed=$((removed + 1))
+        done
+    done
+fi
+
+# ── Android: all connected devices/emulators ────────────────────────────────
+if command -v adb &>/dev/null; then
+    devices=$(adb devices 2>/dev/null | awk 'NR>1 && $2=="device" {print $1}' || true)
+    for serial in $devices; do
+        packages=$(adb -s "$serial" shell pm list packages 2>/dev/null \
+            | tr -d '\r' | sed -n "s/^package:\(${android_prefix//./\\.}[a-z0-9_]*\)$/\1/p" || true)
+        for pkg in $packages; do
+            if [[ "$dry_run" == "1" ]]; then
+                echo "would uninstall (Android $serial): $pkg"
+            else
+                echo "uninstalling (Android $serial): $pkg"
+                adb -s "$serial" uninstall "$pkg" >/dev/null
+            fi
+            removed=$((removed + 1))
+        done
+    done
+fi
+
+if [[ "$removed" == "0" ]]; then
+    echo "no worktree-suffixed Buzz installs found (production apps untouched)"
+elif [[ "$dry_run" == "1" ]]; then
+    echo "dry run: $removed worktree install(s) would be removed (production apps untouched)"
+else
+    echo "removed $removed worktree install(s) (production apps untouched)"
+fi
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Writes worktree-aware identity overrides for mobile debug builds, mirroring
+# the desktop dev experience in scripts/instance-env.sh: debug builds produced
+# from a git worktree get a unique app identifier keyed to the WORKTREE
+# DIRECTORY NAME (stable across branch switches, so installs and login state
+# are bounded by worktree count) plus a display-only branch label (short SHA
+# when detached).
+#
+# In a worktree this writes two gitignored override files consumed by the
+# native build systems (so direct Xcode / Android Studio / `flutter run`
+# builds pick them up too):
+#   mobile/ios/Flutter/WorktreeOverrides.xcconfig  (Debug builds only; a
+#     developer's AppOverrides.xcconfig takes precedence per variable)
+#   mobile/android/worktree.properties             (debug build type only)
+# In the main checkout it removes any stale override files. Release and
+# profile builds never read these overrides.
+set -euo pipefail
+
+# `just mobile-*` recipes unset these before invoking Flutter; do the same so
+# an inherited GIT_DIR pointing elsewhere cannot misdetect the worktree.
+unset GIT_DIR GIT_WORK_TREE
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ios_overrides="$repo_root/mobile/ios/Flutter/WorktreeOverrides.xcconfig"
+android_props="$repo_root/mobile/android/worktree.properties"
+
+# Worktree detection: in the main working tree --git-dir and --git-common-dir
+# are identical; in any linked worktree they differ (same check as
+# scripts/instance-env.sh).
+in_worktree=0
+if git -C "$repo_root" rev-parse --is-inside-work-tree &>/dev/null; then
+    git_dir=$(git -C "$repo_root" rev-parse --git-dir)
+    git_common_dir=$(git -C "$repo_root" rev-parse --git-common-dir 2>/dev/null)
+    if [[ -n "$git_common_dir" && "$git_dir" != "$git_common_dir" ]]; then
+        in_worktree=1
+    fi
+fi
+
+if [[ "$in_worktree" != "1" ]]; then
+    rm -f "$ios_overrides" "$android_props"
+    exit 0
+fi
+
+# Install identity comes from the worktree directory name: stable across
+# branch switches, so one worktree keeps one installed app (and its login
+# state) no matter how many branches it visits.
+worktree_name="$(basename "$repo_root")"
+
+# Display label is context only: the branch name, or a short SHA when the
+# worktree is detached. Sanitized to [A-Za-z0-9._-] so no valid Git ref can
+# break Android string resources or xcconfig values.
+branch=$(git -C "$repo_root" rev-parse --abbrev-ref HEAD)
+if [[ "$branch" == "HEAD" ]]; then
+    label_raw=$(git -C "$repo_root" rev-parse --short HEAD)
+else
+    label_raw="${branch##*/}"
+fi
+label=$(printf '%s' "$label_raw" | sed -e 's/[^A-Za-z0-9._-]/-/g' -e 's/--*/-/g' -e 's/^-//' -e 's/-$//')
+[[ -n "$label" ]] || label="worktree"
+
+# iOS bundle-identifier slug: lowercase, non-alphanumerics collapsed to
+# hyphens (hyphens are valid in bundle identifiers).
+ios_slug=$(printf '%s' "$worktree_name" | tr '[:upper:]' '[:lower:]' | sed -e 's/[^a-z0-9]/-/g' -e 's/--*/-/g' -e 's/^-//' -e 's/-$//')
+[[ -n "$ios_slug" ]] || ios_slug="worktree"
+
+# Android applicationId segments must match [a-z][a-z0-9_]*: swap hyphens for
+# underscores and prefix a letter when the slug starts with a digit.
+android_slug="${ios_slug//-/_}"
+case "$android_slug" in
+    [0-9]*) android_slug="w_$android_slug" ;;
+esac
+
+ios_bundle_id="com.buzz.buzzMobile.${ios_slug}"
+android_suffix=".${android_slug}"
+
+cat > "$ios_overrides" <<XCCONFIG
+// Generated by scripts/mobile-worktree-overrides.sh — gitignored, do not edit.
+// Applies to Debug builds only (included from Flutter/Debug.xcconfig before
+// AppOverrides.xcconfig, so a developer's app-specific overrides win).
+BUNDLE_IDENTIFIER = ${ios_bundle_id}
+APP_DISPLAY_NAME = Buzz (${label})
+XCCONFIG
+
+cat > "$android_props" <<PROPERTIES
+# Generated by scripts/mobile-worktree-overrides.sh — gitignored, do not edit.
+# Applies to the debug build type only (read by android/app/build.gradle.kts).
+label=${label}
+applicationIdSuffix=${android_suffix}
+PROPERTIES
+
+# The printed identifiers are the generated defaults; on iOS a developer's
+# AppOverrides.xcconfig may override them per variable.
+echo "📱 Worktree ${worktree_name}: label \"${label}\" (iOS default ${ios_bundle_id}, Android suffix ${android_suffix})"
@@ -0,0 +1,249 @@
+#!/usr/bin/env bash
+# Regression tests for the mobile worktree identity contract:
+#   - scripts/mobile-worktree-overrides.sh writes debug-only override files in
+#     a worktree and removes them in the main checkout.
+#   - install identity is keyed to the worktree DIRECTORY (stable across
+#     branch switches); the branch (or short SHA when detached) is a
+#     display-only label sanitized to [A-Za-z0-9._-].
+#   - the tracked iOS/Android build files keep production identity, only
+#     consume the overrides in debug configurations, and let a developer's
+#     AppOverrides.xcconfig take precedence over the worktree defaults.
+#   - scripts/mobile-worktree-clean.sh only ever targets suffixed installs,
+#     never the production app ids.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+script="$repo_root/scripts/mobile-worktree-overrides.sh"
+clean_script="$repo_root/scripts/mobile-worktree-clean.sh"
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+failures=0
+fail() {
+  printf 'FAIL: %s\n' "$1" >&2
+  failures=$((failures + 1))
+}
+pass() {
+  printf 'ok: %s\n' "$1"
+}
+
+make_repo() {
+  # $1: repo dir, $2: initial branch name
+  local repo="$1" branch="$2"
+  mkdir -p "$repo/scripts" "$repo/mobile/ios/Flutter" "$repo/mobile/android"
+  cp "$script" "$repo/scripts/mobile-worktree-overrides.sh"
+  git -C "$repo" init -q -b "$branch"
+  git -C "$repo" -c user.name=t -c user.email=t@t commit -q --allow-empty -m init
+}
+
+make_worktree() {
+  # $1: source repo, $2: worktree dir, $3: branch to create
+  local repo="$1" wt="$2" branch="$3"
+  git -C "$repo" worktree add -q -b "$branch" "$wt"
+  mkdir -p "$wt/scripts" "$wt/mobile/ios/Flutter" "$wt/mobile/android"
+  cp "$script" "$wt/scripts/mobile-worktree-overrides.sh"
+}
+
+# ── Main checkout: no overrides, stale files removed ─────────────────────────
+repo="$tmp/main-checkout"
+make_repo "$repo" main
+echo stale > "$repo/mobile/ios/Flutter/WorktreeOverrides.xcconfig"
+echo stale > "$repo/mobile/android/worktree.properties"
+"$repo/scripts/mobile-worktree-overrides.sh" > /dev/null
+if [[ -e "$repo/mobile/ios/Flutter/WorktreeOverrides.xcconfig" || -e "$repo/mobile/android/worktree.properties" ]]; then
+  fail "main checkout must remove stale worktree override files"
+else
+  pass "main checkout removes stale worktree override files"
+fi
+
+# ── Worktree: identity from DIRECTORY name, label from branch ────────────────
+wt="$tmp/Feature_Work-1"
+make_worktree "$repo" "$wt" "tho/Fix_Thing-2"
+out="$("$wt/scripts/mobile-worktree-overrides.sh")"
+ios="$wt/mobile/ios/Flutter/WorktreeOverrides.xcconfig"
+android="$wt/mobile/android/worktree.properties"
+[[ -f "$ios" && -f "$android" ]] || fail "worktree must write both override files"
+grep -q '^BUNDLE_IDENTIFIER = com\.buzz\.buzzMobile\.feature-work-1$' "$ios" \
+  && pass "iOS bundle identifier keys to the sanitized worktree directory name" \
+  || fail "iOS bundle identifier must key to the worktree dir, got: $(cat "$ios")"
+grep -q '^APP_DISPLAY_NAME = Buzz (Fix_Thing-2)$' "$ios" \
+  && pass "iOS display name carries the branch label" \
+  || fail "iOS display name wrong: $(cat "$ios")"
+grep -q '^label=Fix_Thing-2$' "$android" \
+  && pass "Android label carries the branch label" \
+  || fail "Android label wrong: $(cat "$android")"
+grep -q '^applicationIdSuffix=\.feature_work_1$' "$android" \
+  && pass "Android applicationIdSuffix keys to the worktree directory name" \
+  || fail "Android applicationIdSuffix wrong: $(cat "$android")"
+printf '%s' "$out" | grep -q 'Worktree Feature_Work-1' \
+  && pass "worktree run reports the worktree name" \
+  || fail "worktree run must report the worktree name, got: $out"
+
+# ── Branch switch in the same worktree: identity stable, label follows ───────
+git -C "$wt" checkout -q -b "another/branch-name"
+"$wt/scripts/mobile-worktree-overrides.sh" > /dev/null
+grep -q '^BUNDLE_IDENTIFIER = com\.buzz\.buzzMobile\.feature-work-1$' "$ios" \
+  && grep -q '^applicationIdSuffix=\.feature_work_1$' "$android" \
+  && pass "branch switch keeps the install identity stable (per worktree)" \
+  || fail "install identity must not change on branch switch"
+grep -q '^label=branch-name$' "$android" \
+  && pass "branch switch updates the display label" \
+  || fail "display label must follow the branch, got: $(cat "$android")"
+
+# ── Apostrophes / exotic-but-valid refs: label is sanitized ──────────────────
+git -C "$wt" checkout -q -b "it's-\$a\"branch"
+"$wt/scripts/mobile-worktree-overrides.sh" > /dev/null
+grep -q "^label=it-s-a-branch$" "$android" \
+  && pass "apostrophes and shell metacharacters are sanitized out of the label" \
+  || fail "label must sanitize special chars, got: $(cat "$android")"
+grep -Eq "^APP_DISPLAY_NAME = Buzz \([A-Za-z0-9._-]+\)$" "$ios" \
+  && pass "iOS display name only contains resource-safe characters" \
+  || fail "iOS display name has unsafe characters: $(cat "$ios")"
+
+# ── Detached HEAD: label falls back to the short SHA ──────────────────────────
+sha="$(git -C "$wt" rev-parse --short HEAD)"
+git -C "$wt" checkout -q --detach
+"$wt/scripts/mobile-worktree-overrides.sh" > /dev/null
+grep -q "^label=${sha}$" "$android" \
+  && pass "detached HEAD labels with the short SHA instead of literal HEAD" \
+  || fail "detached HEAD must use short SHA, got: $(cat "$android")"
+grep -q '^applicationIdSuffix=\.feature_work_1$' "$android" \
+  && pass "detached HEAD keeps the per-worktree install identity" \
+  || fail "detached HEAD must not change the install identity"
+
+# ── Digit-leading worktree dir gets a letter-prefixed Android segment ────────
+wt2="$tmp/2fast"
+make_worktree "$repo" "$wt2" "some-branch"
+"$wt2/scripts/mobile-worktree-overrides.sh" > /dev/null
+grep -q '^applicationIdSuffix=\.w_2fast$' "$wt2/mobile/android/worktree.properties" \
+  && pass "digit-leading worktree dir yields a valid Android package segment" \
+  || fail "digit-leading dir segment wrong: $(cat "$wt2/mobile/android/worktree.properties")"
+
+# ── Tracked build files: overrides are debug-only, release stays production ──
+debug_xcconfig="$repo_root/mobile/ios/Flutter/Debug.xcconfig"
+release_xcconfig="$repo_root/mobile/ios/Flutter/Release.xcconfig"
+gradle="$repo_root/mobile/android/app/build.gradle.kts"
+manifest="$repo_root/mobile/android/app/src/main/AndroidManifest.xml"
+plist="$repo_root/mobile/ios/Runner/Info.plist"
+
+grep -q 'WorktreeOverrides.xcconfig' "$debug_xcconfig" \
+  && pass "Debug.xcconfig includes WorktreeOverrides" \
+  || fail "Debug.xcconfig must include WorktreeOverrides.xcconfig"
+worktree_line=$(grep -n 'WorktreeOverrides.xcconfig' "$debug_xcconfig" | cut -d: -f1 | head -1)
+app_line=$(grep -n 'AppOverrides.xcconfig' "$debug_xcconfig" | grep '#include' | cut -d: -f1 | tail -1)
+if [[ -n "$worktree_line" && -n "$app_line" && "$worktree_line" -lt "$app_line" ]]; then
+  pass "AppOverrides is included after WorktreeOverrides (developer overrides win)"
+else
+  fail "Debug.xcconfig must include AppOverrides.xcconfig after WorktreeOverrides.xcconfig"
+fi
+grep -q 'WorktreeOverrides' "$release_xcconfig" \
+  && fail "Release.xcconfig must not include WorktreeOverrides.xcconfig" \
+  || pass "Release.xcconfig does not include WorktreeOverrides"
+grep -q '^BUNDLE_IDENTIFIER = com\.buzz\.buzzMobile$' "$release_xcconfig" \
+  && pass "Release.xcconfig keeps the production bundle identifier" \
+  || fail "Release.xcconfig must keep BUNDLE_IDENTIFIER = com.buzz.buzzMobile"
+grep -q '^APP_DISPLAY_NAME = Buzz$' "$release_xcconfig" \
+  && pass "Release.xcconfig keeps the production display name" \
+  || fail "Release.xcconfig must keep APP_DISPLAY_NAME = Buzz"
+grep -q '<string>$(APP_DISPLAY_NAME)</string>' "$plist" \
+  && pass "Info.plist display name resolves from build settings" \
+  || fail "Info.plist CFBundleDisplayName must be \$(APP_DISPLAY_NAME)"
+grep -q 'android:label="@string/app_name"' "$manifest" \
+  && pass "Android manifest label resolves from resources" \
+  || fail "Android manifest label must be @string/app_name"
+grep -q 'resValue("string", "app_name", "Buzz")' "$gradle" \
+  && pass "Gradle default app_name stays Buzz" \
+  || fail "Gradle must declare the default app_name resValue"
+grep -q 'worktreeLabel.matches' "$gradle" \
+  && pass "Gradle validates the worktree label before use" \
+  || fail "Gradle must validate the worktree label against a safe pattern"
+
+# Extract a brace-balanced block: everything from the first line matching $2
+# to the line where its braces close. Unlike a /start/,/}/ awk range, nested
+# blocks cannot end the scan early.
+extract_block() {
+  # $1: file (or - for stdin), $2: start regex
+  awk -v start="$2" '
+    !in_block && $0 ~ start { in_block = 1 }
+    in_block {
+      print
+      depth += gsub(/\{/, "{") - gsub(/\}/, "}")
+      if (depth <= 0) exit
+    }
+  ' "$1"
+}
+
+# Self-test: the extractor must see past a nested block — this is exactly the
+# hole the old /release \{/,/\}/ range had.
+sneaky=$'buildTypes {\n  release {\n    if (nested) {\n      x = 1\n    }\n    worktreeSneakyReference()\n  }\n}'
+printf '%s\n' "$sneaky" | extract_block - 'release \{' | grep -q 'worktreeSneakyReference' \
+  && pass "release-block extractor scans past nested braces" \
+  || fail "release-block extractor must not stop at the first nested close brace"
+
+# The worktree suffix/label must only appear inside the debug build type.
+extract_block "$gradle" 'buildTypes \{' | extract_block - 'release \{' | grep -q 'worktree' \
+  && fail "release build type must not reference worktree identity" \
+  || pass "release build type does not reference worktree identity"
+
+git -C "$repo_root" check-ignore -q mobile/ios/Flutter/WorktreeOverrides.xcconfig \
+  && pass "iOS override file is gitignored" \
+  || fail "mobile/ios/Flutter/WorktreeOverrides.xcconfig must be gitignored"
+git -C "$repo_root" check-ignore -q mobile/android/worktree.properties \
+  && pass "Android override file is gitignored" \
+  || fail "mobile/android/worktree.properties must be gitignored"
+grep -Eq '^\s+\./scripts/mobile-worktree-overrides\.sh$' "$repo_root/Justfile" \
+  && pass "just mobile-dev applies the worktree identity" \
+  || fail "Justfile mobile-dev must run scripts/mobile-worktree-overrides.sh"
+grep -Eq '^\s+\./scripts/mobile-worktree-clean\.sh$' "$repo_root/Justfile" \
+  && pass "just mobile-clean is wired to the cleanup script" \
+  || fail "Justfile mobile-clean must run scripts/mobile-worktree-clean.sh"
+
+# ── Cleanup safety: suffixed installs matched, production ids preserved ──────
+stub_bin="$tmp/stub-bin"
+mkdir -p "$stub_bin"
+cat > "$stub_bin/adb" <<'STUB'
+#!/usr/bin/env bash
+case "$1 $2" in
+  "devices ") printf 'List of devices attached\nemulator-5554\tdevice\n' ;;
+esac
+if [[ "$1" == "devices" ]]; then exit 0; fi
+if [[ "$3 $4 $5" == "shell pm list" ]]; then
+  printf 'package:xyz.block.buzz.mobile\n'
+  printf 'package:xyz.block.buzz.mobile.feature_work_1\n'
+  printf 'package:xyz.block.buzz.mobile.w_2fast\n'
+  printf 'package:com.android.settings\n'
+  exit 0
+fi
+if [[ "$3" == "uninstall" ]]; then echo Success; exit 0; fi
+exit 0
+STUB
+chmod +x "$stub_bin/adb"
+# No xcrun stub: the iOS pass is skipped when xcrun is absent, which also
+# keeps this test honest on Linux CI.
+clean_out="$(PATH="$stub_bin:/usr/bin:/bin" bash "$clean_script" --dry-run)"
+printf '%s\n' "$clean_out" | grep -q 'xyz\.block\.buzz\.mobile\.feature_work_1' \
+  && pass "cleanup targets worktree-suffixed Android installs" \
+  || fail "cleanup must list suffixed installs, got: $clean_out"
+printf '%s\n' "$clean_out" | grep -q 'xyz\.block\.buzz\.mobile\.w_2fast' \
+  && pass "cleanup targets letter-prefixed suffixed installs" \
+  || fail "cleanup must list w_-prefixed installs, got: $clean_out"
+printf '%s\n' "$clean_out" | grep -q 'mobile\.feature_work_1' || true
+if printf '%s\n' "$clean_out" | grep -Eq '(would uninstall|uninstalling).*xyz\.block\.buzz\.mobile$'; then
+  fail "cleanup must never target the production Android app id"
+else
+  pass "cleanup preserves the production Android app id"
+fi
+if printf '%s\n' "$clean_out" | grep -q 'com\.android\.settings'; then
+  fail "cleanup must never target unrelated packages"
+else
+  pass "cleanup ignores unrelated packages"
+fi
+printf '%s\n' "$clean_out" | grep -q 'dry run:' \
+  && pass "cleanup --dry-run reports without uninstalling" \
+  || fail "cleanup --dry-run must report a dry-run summary, got: $clean_out"
+
+if [[ "$failures" -gt 0 ]]; then
+  printf '%d failure(s)\n' "$failures" >&2
+  exit 1
+fi
+printf 'all mobile worktree identity contract checks passed\n'