gowalk-cicd 1.0.52 → 1.0.53

package/CLAUDE.md

@@ -178,6 +178,23 @@ node /path/to/gowalk-cicd/bin/cli.mjs
   pinned exactly because the Android job holds the keystore and the Play
   service account; the CLI runs from a temp cwd so its `.crashlytics/` debris
   never lands in the checkout.
+- The iOS action reads every script and prompt from the snapshot it takes of
+  itself in its first step (`$SWIFT_APP_ACTION`, under `RUNNER_TEMP`), never
+  from `${{ github.action_path }}` after that step. The plugin self-update
+  (`autoupdate_check.sh`) runs right after the snapshot and commits on its own,
+  before the version/signing/archive steps, so a red deploy still receives the
+  release that fixes it; the snapshot is what keeps that run on one version.
+  `test_action_step_order.py` pins both. A new script reference in
+  `action/action.yml` therefore uses `"$SWIFT_APP_ACTION/scripts/..."`.
+- Two situations end a green job with work for the panel, and each is a typed
+  check-run annotation (`::notice title=<name>::<one-line JSON with a versioned
+  schema>`), never prose in a `::warning::`: `play_review_pending`
+  (`templates/deploy.yml`, Play refused auto-submit and the bundle landed
+  unsubmitted) and `store_version_locked` (`action/action.yml`, the
+  `TESTFLIGHT_ONLY` decision of `manage_marketing_version.py`: an App Store
+  version is under review, so the build shipped to TestFlight under that
+  version and metadata was skipped). The README table lists the schemas; add a
+  field by bumping the version.
 - The JDK is chosen by `scripts/select_jdk.py`, called from the workflow before
   `setup-java`. The `JAVA_VERSION` repo variable always wins; otherwise Flutter
   gets 17 and native Gradle gets 21, except that a positively-detected Kotlin

package/README.md

@@ -217,13 +217,72 @@ sent for review from the Google Play Console UI.
 
 That fails the whole upload, so the bundle you just built never reaches Play at
 all. The retry re-uploads with `changesNotSentForReview`, which lands the bundle
-and leaves it waiting, then emits a `::warning::` naming the package. Someone
-then presses **Send changes for review** on that app's Publishing overview page.
-There is no API for that press — it is the one step Google deliberately reserves
-for a human, and no amount of tooling removes it.
+and leaves it waiting, then records that fact as a typed check-run annotation on
+the job (see [Check-run annotations](#check-run-annotations-the-panel-reads)):
+
+```
+::notice title=play_review_pending::{"schema":"gowalk-cicd/play-review-pending.v1",
+  "package":"<applicationId>","track":"<track>","version_code":"<versionCode>"}
+```
+
+There is no API for the **Send changes for review** press — Google reserves it
+for the Play Console — so the panel that merged the commit reads the annotation
+and opens its own Play console step, which promotes the uploaded version code to
+the track Google named and presses it. Nobody is asked to notice a warning.
 
 In the ordinary case the first upload submits normally and the retry is skipped.
 
+### When an App Store version is in review
+
+While any App Store version of the app is `WAITING_FOR_REVIEW`, `IN_REVIEW` or
+`PENDING_DEVELOPER_RELEASE`, App Store Connect refuses to create or edit **any**
+version — every `POST /appStoreVersions` answers
+`409 ENTITY_ERROR.RELATIONSHIP.INVALID` ("You cannot create a new version of the
+App in the current state"), whatever version string is asked for. The version
+step used to see only rows at the project's own `MARKETING_VERSION`, so a sibling
+in review (1.6.3 under review, project at 1.6.4) went unnoticed, CREATE was
+attempted and the deploy failed on every push until the review ended.
+
+The decision is now `TESTFLIGHT_ONLY`: the build is stamped with the **locked**
+version string (so it joins that version's TestFlight train instead of opening a
+new marketing-version train), the build number still advances, the archive is
+uploaded to TestFlight, and the App Store metadata steps are skipped. The project
+file is never touched — `MARKETING_VERSION` stays the source of truth for the next
+release. The job records a typed annotation so the panel knows the build went to
+TestFlight only:
+
+```
+::notice title=store_version_locked::{"schema":"gowalk-cicd/store-version-locked.v1",
+  "version":"1.6.3","state":"WAITING_FOR_REVIEW","build_number":"239"}
+```
+
+### Check-run annotations the panel reads
+
+Two situations end a green job with work left for something other than this
+workflow. Each is recorded as a GitHub check-run annotation whose **title** names
+the situation and whose **message** is one line of JSON carrying a versioned
+`schema`. The panel that merged the commit reads them through the check-runs API
+— never by parsing log text — so the title and schema are a contract:
+
+| title | schema | fields |
+| --- | --- | --- |
+| `play_review_pending` | `gowalk-cicd/play-review-pending.v1` | `package`, `track`, `version_code` |
+| `store_version_locked` | `gowalk-cicd/store-version-locked.v1` | `version`, `state`, `build_number` |
+
+Add a field by bumping the schema version; never change the meaning of an
+existing one.
+
+### The plugin self-update runs first
+
+The vendored iOS action checks npm for a newer `gowalk-cicd` at the **start** of
+every default-branch run and commits the refreshed action directories in their
+own commit, before the version, signing and archive steps. A deploy that is red
+in one of those steps therefore still picks up the plugin release that fixes it,
+on the very run that fails, and the next push runs the fixed plugin. The run that
+performed the update keeps executing the version it started with: the action
+snapshots itself to `$RUNNER_TEMP` before anything mutates and reads every script
+and prompt from that copy.
+
 ### Google Play upload retry
 
 A Play edit is a short-lived server-side object, and an AAB upload that runs
@@ -604,8 +663,11 @@ Feature-branch runs installed from the standard workflow still archive and
 upload to TestFlight, but pass `manage-app-store-version: 'false'`. This keeps
 branch validation independent of the editable App Store release slot, so a
 build can upload while the current release is locked in review. Default-branch
-runs retain version creation and metadata automation. Direct action callers
-keep the historical behavior because the new input defaults to `true`.
+runs retain version creation and metadata automation — and while a version is
+locked in review they take the same TestFlight-only path on their own (see
+[When an App Store version is in review](#when-an-app-store-version-is-in-review)).
+Direct action callers keep the historical behavior because the new input
+defaults to `true`.
 
 ### App ID capabilities
 

package/action/.daemux-version

@@ -1 +1 @@
-1.0.52
+1.0.53

package/action/action.yml

@@ -187,6 +187,79 @@ inputs:
 runs:
   using: composite
   steps:
+    # Every later step reads this action's scripts and prompts from the
+    # snapshot, never from ${action_path}. The autoupdate below re-vendors
+    # .github/actions/swift-app/ — the same directory as ${action_path} for
+    # local-action consumers — while this run is still executing the
+    # action.yml the runner loaded at job start. Reading scripts from the
+    # refreshed tree under the old step definitions is a mid-run version
+    # mix; one copy taken before anything mutates keeps the whole run on
+    # one version of the plugin.
+    - name: Snapshot this action for the whole run
+      shell: bash
+      run: |
+        set -euo pipefail
+        rm -rf "$RUNNER_TEMP/swift-app-action"
+        mkdir -p "$RUNNER_TEMP/swift-app-action"
+        cp -R "${{ github.action_path }}/." "$RUNNER_TEMP/swift-app-action/"
+        echo "SWIFT_APP_ACTION=$RUNNER_TEMP/swift-app-action" >> "$GITHUB_ENV"
+
+    # The plugin self-update runs BEFORE the version, signing and archive
+    # steps and lands in its own commit. It used to run after them, so a
+    # deploy that was red in the version step (App Store Connect refusing a
+    # new version while one is in review, GoVolt run 33743284641) never
+    # reached the self-update, and the plugin release that fixed exactly
+    # that failure could not arrive in the repository that needed it.
+    # Committing here rather than with the cert refresh below is the same
+    # point: a red step later in this run must not take the update with it.
+    - name: Stage bot-side scripts to runner temp
+      if: ${{ (inputs.archive == 'true' || inputs.auto-update == 'true')
+            && github.event_name == 'push'
+            && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+      shell: bash
+      run: |
+        set -euo pipefail
+        mkdir -p "$RUNNER_TEMP/swift-app-bot-scripts"
+        cp "$SWIFT_APP_ACTION/scripts/autoupdate_check.sh" \
+          "$RUNNER_TEMP/swift-app-bot-scripts/"
+        cp "$SWIFT_APP_ACTION/scripts/commit_bot_changes.sh" \
+          "$RUNNER_TEMP/swift-app-bot-scripts/"
+        chmod +x "$RUNNER_TEMP/swift-app-bot-scripts/"*.sh
+        echo "BOT_SCRIPTS_DIR=$RUNNER_TEMP/swift-app-bot-scripts" >> "$GITHUB_ENV"
+
+    - name: Check for app-ci update
+      # Default branch + push event only. `auto-update` is on by default;
+      # consumers can pin via `false`. Runs from $BOT_SCRIPTS_DIR
+      # (RUNNER_TEMP) so its own `npx` overwriting ${action_path} cannot
+      # swap the script under us.
+      if: ${{ inputs.auto-update == 'true'
+            && github.event_name == 'push'
+            && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+      shell: bash
+      working-directory: ${{ github.workspace }}
+      run: bash "$BOT_SCRIPTS_DIR/autoupdate_check.sh"
+
+    - name: Commit + push refreshed app-ci
+      # Its own commit, immediately: the refreshed action files must reach
+      # the default branch even when the version or signing steps of this
+      # very run fail. deploy.yml is deliberately not staged (GITHUB_TOKEN
+      # cannot push workflow files). No-op when the plugin was current.
+      if: ${{ inputs.auto-update == 'true'
+            && github.event_name == 'push'
+            && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+      shell: bash
+      working-directory: ${{ github.workspace }}
+      env:
+        GITHUB_REF_NAME: ${{ github.ref_name }}
+      run: |
+        set -euo pipefail
+        # A shallow checkout (fetch-depth 1 for direct action callers) must
+        # be able to rebase on a moved default branch inside the push retry.
+        git fetch --unshallow 2>/dev/null \
+          || git fetch --depth=2147483647 2>/dev/null \
+          || true
+        bash "$BOT_SCRIPTS_DIR/commit_bot_changes.sh"
+
     - name: Resolve credentials + auto-detect Xcode project
       shell: bash
       env:
@@ -217,7 +290,7 @@ runs:
           echo "Installing xcodegen (project.yml present, binary missing)…"
           brew install xcodegen >/dev/null 2>&1 || HOMEBREW_NO_AUTO_UPDATE=1 brew install xcodegen
         fi
-        python3 "${{ github.action_path }}/scripts/read_config.py"
+        python3 "$SWIFT_APP_ACTION/scripts/read_config.py"
 
     - name: Select latest Xcode
       shell: bash
@@ -303,10 +376,12 @@ runs:
         CONFIGURATION: ${{ inputs.configuration || env.CFG_CONFIGURATION }}
       run: |
         set -o pipefail
-        python3 "${{ github.action_path }}/scripts/resolve_marketing_version.py" \
+        python3 "$SWIFT_APP_ACTION/scripts/resolve_marketing_version.py" \
           | tee -a "$GITHUB_ENV"
 
     - name: Resolve App Store version slot (REUSE or CREATE)
+      # A third answer, TESTFLIGHT_ONLY, is handled inside: see the
+      # STORE_VERSION_LOCKED branch of the script.
       if: ${{ inputs.archive == 'true' && inputs.manage-app-store-version == 'true' }}
       shell: bash
       env:
@@ -332,19 +407,40 @@ runs:
         CONFIGURATION: ${{ inputs.configuration || env.CFG_CONFIGURATION }}
       run: |
         set -o pipefail
-        BUILD_NUMBER=$(python3 "${{ github.action_path }}/scripts/next_build_number.py")
-        DECISION_JSON=$(python3 "${{ github.action_path }}/scripts/manage_marketing_version.py")
+        BUILD_NUMBER=$(python3 "$SWIFT_APP_ACTION/scripts/next_build_number.py")
+        DECISION_JSON=$(python3 "$SWIFT_APP_ACTION/scripts/manage_marketing_version.py")
         APP_STORE_VERSION_ID=$(python3 -c \
           "import json,sys; d=json.loads(sys.argv[1]); print(d.get('appStoreVersionId',''))" \
           "$DECISION_JSON")
+        DECISION=$(python3 -c \
+          "import json,sys; d=json.loads(sys.argv[1]); print(d.get('decision',''))" \
+          "$DECISION_JSON")
         # The decision's versionString is authoritative: it reflects any
         # auto-bump that mmv applied to MARKETING_VERSION when the project
-        # was below the ASC combined floor. Re-export so subsequent steps
-        # (Stamp Info.plist, Archive) see the bumped value.
+        # was below the ASC combined floor — or, for TESTFLIGHT_ONLY, the
+        # App Store version Apple is holding, which is the train this build
+        # joins. Re-export so subsequent steps (Stamp Info.plist, Archive)
+        # see that value.
         EFFECTIVE_MV=$(python3 -c \
           "import json,sys; d=json.loads(sys.argv[1]); print(d.get('versionString',''))" \
           "$DECISION_JSON")
-        if [ -n "$EFFECTIVE_MV" ] && [ "$EFFECTIVE_MV" != "$MARKETING_VERSION" ]; then
+        if [ "$DECISION" = "TESTFLIGHT_ONLY" ]; then
+          # An App Store version is under review or awaiting the developer's
+          # release: App Store Connect refuses to create or edit ANY version
+          # (409 ENTITY_ERROR.RELATIONSHIP.INVALID). The build still ships to
+          # TestFlight, stamped with the locked version so it lands in that
+          # version's train; App Store metadata below is skipped
+          # (STORE_VERSION_LOCKED), and the typed check-run annotation tells
+          # the panel that merged this commit exactly what happened.
+          LOCKED_STATE=$(python3 -c \
+            "import json,sys; d=json.loads(sys.argv[1]); print(d.get('state',''))" \
+            "$DECISION_JSON")
+          echo "::notice::App Store version $EFFECTIVE_MV is $LOCKED_STATE; uploading build $BUILD_NUMBER to TestFlight under $EFFECTIVE_MV and skipping App Store metadata"
+          echo "STORE_VERSION_LOCKED=$EFFECTIVE_MV" >> "$GITHUB_ENV"
+          echo "::notice title=store_version_locked::{\"schema\":\"gowalk-cicd/store-version-locked.v1\",\"version\":\"$EFFECTIVE_MV\",\"state\":\"$LOCKED_STATE\",\"build_number\":\"$BUILD_NUMBER\"}"
+          echo "MARKETING_VERSION=$EFFECTIVE_MV" >> "$GITHUB_ENV"
+          MARKETING_VERSION="$EFFECTIVE_MV"
+        elif [ -n "$EFFECTIVE_MV" ] && [ "$EFFECTIVE_MV" != "$MARKETING_VERSION" ]; then
           echo "::notice::auto-bump rewrote MARKETING_VERSION $MARKETING_VERSION -> $EFFECTIVE_MV"
           echo "MARKETING_VERSION=$EFFECTIVE_MV" >> "$GITHUB_ENV"
           MARKETING_VERSION="$EFFECTIVE_MV"
@@ -360,7 +456,7 @@ runs:
         APP_STORE_APPLE_ID: ${{ inputs.app-store-apple-id || env.CFG_APP_STORE_APPLE_ID }}
       run: |
         set -o pipefail
-        BUILD_NUMBER=$(python3 "${{ github.action_path }}/scripts/next_build_number.py")
+        BUILD_NUMBER=$(python3 "$SWIFT_APP_ACTION/scripts/next_build_number.py")
         echo "BUILD_NUMBER=$BUILD_NUMBER" >> "$GITHUB_ENV"
         echo "APP_STORE_VERSION_ID=" >> "$GITHUB_ENV"
         echo "Using marketing version $MARKETING_VERSION build $BUILD_NUMBER without an App Store version slot"
@@ -383,7 +479,7 @@ runs:
         CERTIFICATE_CAP_POLICY: ${{ inputs.certificate-cap-policy }}
       run: |
         set +e
-        python3 "${{ github.action_path }}/scripts/prepare_signing.py"
+        python3 "$SWIFT_APP_ACTION/scripts/prepare_signing.py"
         signing_exit=$?
         set -e
         echo "SIGNING_PREP_EXIT=$signing_exit" >> "$GITHUB_ENV"
@@ -408,36 +504,13 @@ runs:
     #     of any compromised step in the workflow — keep workflow minimal.
     #   - .gitignore must NOT block the new creds/ files (see setup doc).
     #
-    # Split into four steps so cert refresh and autoupdate can both fire
-    # in a single combined commit when they coincide, but either can fire
-    # alone without redundant retries: (1) copy bot scripts to RUNNER_TEMP
-    # so autoupdate's `npx` cannot mid-run swap script bytes under us,
-    # (2) stage cert files, (3) check for newer app-ci on npm and
-    # stage refreshed action files, (4) commit + push whatever is staged,
-    # (5) re-raise a deferred prepare failure after preserving its cache.
+    # The autoupdate half runs FIRST in this action (see the top of the
+    # step list) and lands in its own commit, so a fixed plugin reaches a
+    # repository whose deploy is failing in the version or signing steps
+    # below. What remains here: (1) stage cert files, (2) commit + push
+    # whatever is staged, (3) re-raise a deferred prepare failure after
+    # preserving its cache.
 
-    # Stage scripts to RUNNER_TEMP so the autoupdate step's `npx` (which
-    # overwrites .github/actions/swift-app/ — the same dir as ${action_path}
-    # for local-action consumers) cannot mid-run swap the script bytes
-    # under us. action.yml step definitions are already loaded by the
-    # runner at job start, but the shell scripts are read fresh per step,
-    # so without this stage we'd risk loading commit_bot_changes.sh from
-    # the post-`npx` (newer) tree while the surrounding step definitions
-    # came from the pre-`npx` (older) action.yml — a mid-run version mix.
-    - name: Stage bot-side scripts to runner temp
-      if: ${{ (inputs.archive == 'true' || inputs.auto-update == 'true')
-            && github.event_name == 'push'
-            && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
-      shell: bash
-      run: |
-        set -euo pipefail
-        mkdir -p "$RUNNER_TEMP/swift-app-bot-scripts"
-        cp "${{ github.action_path }}/scripts/autoupdate_check.sh" \
-          "$RUNNER_TEMP/swift-app-bot-scripts/"
-        cp "${{ github.action_path }}/scripts/commit_bot_changes.sh" \
-          "$RUNNER_TEMP/swift-app-bot-scripts/"
-        chmod +x "$RUNNER_TEMP/swift-app-bot-scripts/"*.sh
-        echo "BOT_SCRIPTS_DIR=$RUNNER_TEMP/swift-app-bot-scripts" >> "$GITHUB_ENV"
 
     - name: Stage refreshed signing identity
       # Only stage on push to the default branch — PR runs and feature
@@ -495,25 +568,14 @@ runs:
           sed 's/^/  /' "$bump_marker"
         fi
 
-    - name: Check for app-ci update
-      # Same gate as cert staging: default branch + push event only.
-      # `auto-update` is on by default; consumers can pin via `false`.
-      # Runs from $BOT_SCRIPTS_DIR (RUNNER_TEMP) so its own `npx`
-      # overwriting ${action_path} mid-run can't swap the script under us.
-      if: ${{ inputs.auto-update == 'true'
-            && github.event_name == 'push'
-            && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
-      shell: bash
-      working-directory: ${{ github.workspace }}
-      run: bash "$BOT_SCRIPTS_DIR/autoupdate_check.sh"
-
     - name: Commit + push staged bot changes
-      # Fires when EITHER cert staging OR autoupdate could have produced
-      # diffs. The script itself is a no-op when nothing is staged, so a
+      # The cert refresh (and any marketing-version auto-bump the version
+      # step staged). The autoupdate landed in its own commit at the top of
+      # this action; this script is a no-op when nothing is staged, so a
       # PR / feature-branch run that somehow reaches this step does no
       # harm — but we still gate on default-branch push for clarity.
-      # Runs from $BOT_SCRIPTS_DIR (RUNNER_TEMP) — see step above for why
-      # we don't read directly from ${action_path} after autoupdate.
+      # Runs from $BOT_SCRIPTS_DIR (RUNNER_TEMP): the autoupdate re-vendored
+      # ${action_path} earlier in this run and must not swap scripts under us.
       if: ${{ (inputs.archive == 'true' || inputs.auto-update == 'true')
             && github.event_name == 'push'
             && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
@@ -735,7 +797,7 @@ runs:
         PROJECT: ${{ inputs.project || env.CFG_PROJECT }}
         WORKSPACE: ${{ inputs.workspace || env.CFG_WORKSPACE }}
       run: |
-        python3 "${{ github.action_path }}/scripts/crashlytics_dsyms.py" \
+        python3 "$SWIFT_APP_ACTION/scripts/crashlytics_dsyms.py" \
           --archive "$RUNNER_TEMP/app.xcarchive" \
           --search-root "$(dirname "${WORKSPACE:-$PROJECT}")"
 
@@ -766,18 +828,22 @@ runs:
         fi
         echo "Upload succeeded"
 
+    # Both App Store metadata writers are skipped while an App Store version
+    # is locked (STORE_VERSION_LOCKED, the TESTFLIGHT_ONLY decision): there is
+    # no editable version id to write to, and each script requires one.
     - name: Detect empty ASC metadata fields
       id: detect_metadata
       if: >-
         ${{ inputs.archive == 'true' && inputs.upload == 'true'
-            && inputs.manage-app-store-version == 'true' && inputs.ai-metadata != 'false' }}
+            && inputs.manage-app-store-version == 'true' && inputs.ai-metadata != 'false'
+            && env.STORE_VERSION_LOCKED == '' }}
       shell: bash
       env:
         APP_STORE_APPLE_ID: ${{ inputs.app-store-apple-id || env.CFG_APP_STORE_APPLE_ID }}
         APP_STORE_VERSION_ID: ${{ env.APP_STORE_VERSION_ID }}
       run: |
         set -o pipefail
-        python3 "${{ github.action_path }}/scripts/asc_metadata_detector.py" \
+        python3 "$SWIFT_APP_ACTION/scripts/asc_metadata_detector.py" \
           > "$RUNNER_TEMP/asc_empty_metadata.json" || {
             echo "::warning::metadata detector failed; skipping AI step"
             echo "has_empty=false" >> "$GITHUB_OUTPUT"
@@ -800,7 +866,7 @@ runs:
         BUNDLE_ID: ${{ inputs.bundle-id || env.CFG_BUNDLE_ID }}
         SCHEME: ${{ inputs.scheme || env.CFG_SCHEME }}
       run: |
-        python3 "${{ github.action_path }}/scripts/app_context_scanner.py" \
+        python3 "$SWIFT_APP_ACTION/scripts/app_context_scanner.py" \
           > "$RUNNER_TEMP/app_context.txt"
         wc -c "$RUNNER_TEMP/app_context.txt"
 
@@ -834,7 +900,7 @@ runs:
       if: ${{ steps.derive_phases.outputs.needs_phase1 == 'true' }}
       shell: bash
       env:
-        TEMPLATE_PATH: ${{ github.action_path }}/prompts/generate_descriptions.prompt.yml
+        TEMPLATE_PATH: ${{ env.SWIFT_APP_ACTION }}/prompts/generate_descriptions.prompt.yml
       run: |
         # Pre-render via PyYAML so multi-line app_context stays a block scalar
         # and doesn't break ai-inference@v1's naive string substitution.
@@ -905,7 +971,7 @@ runs:
           echo "phase1_ok=false" >> "$GITHUB_OUTPUT"
           exit 0
         fi
-        python3 "${{ github.action_path }}/scripts/asc_metadata_applier.py" \
+        python3 "$SWIFT_APP_ACTION/scripts/asc_metadata_applier.py" \
           --state "$RUNNER_TEMP/asc_empty_metadata.json" \
           --response "$OUT" \
           --fields-filter description
@@ -917,7 +983,7 @@ runs:
                 || steps.phase1_apply.outputs.phase1_ok == 'true') }}
       shell: bash
       env:
-        TEMPLATE_PATH: ${{ github.action_path }}/prompts/generate_dependent_fields.prompt.yml
+        TEMPLATE_PATH: ${{ env.SWIFT_APP_ACTION }}/prompts/generate_dependent_fields.prompt.yml
       run: |
         # Merge existing_fields.{locale}.description with Phase-1 outputs to
         # produce authoritative per-locale description context, then render
@@ -1010,7 +1076,7 @@ runs:
           head -c 500 "$OUT" || true
           echo
         fi
-        python3 "${{ github.action_path }}/scripts/asc_metadata_applier.py" \
+        python3 "$SWIFT_APP_ACTION/scripts/asc_metadata_applier.py" \
           --state "$RUNNER_TEMP/asc_empty_metadata.json" \
           --response "$OUT" \
           --fields-filter name,subtitle,keywords,promotionalText,whatsNew
@@ -1026,6 +1092,7 @@ runs:
     - name: Set App Store "What's New"
       if: ${{ inputs.archive == 'true' && inputs.upload == 'true'
             && inputs.manage-app-store-version == 'true'
+            && env.STORE_VERSION_LOCKED == ''
             && (inputs.app-store-whats-new != '' || env.CFG_WHATS_NEW != '') }}
       shell: bash
       env:
@@ -1051,4 +1118,4 @@ runs:
           WHATS_NEW_ONLY_IF_EMPTY=false
         fi
         export APP_STORE_WHATS_NEW_FILE WHATS_NEW_ONLY_IF_EMPTY
-        python3 "${{ github.action_path }}/scripts/set_app_store_whats_new.py"
+        python3 "$SWIFT_APP_ACTION/scripts/set_app_store_whats_new.py"

package/action/scripts/manage_marketing_version.py

@@ -10,14 +10,24 @@ build number is bumped automatically (see next_build_number.py).
 Algorithm:
   1. Read MARKETING_VERSION from env (set by action.yml from
      xcodebuild -showBuildSettings or PlistBuddy).
-  2. Floor-check (non-strict): target >= combined floor across
+  2. Store lock: if ANY App Store version is under Apple Review
+     (WAITING_FOR_REVIEW / IN_REVIEW) or approved and awaiting the
+     developer's release click (PENDING_DEVELOPER_RELEASE), no App Store
+     version can be created or edited at all -- App Store Connect answers
+     every POST with 409 ENTITY_ERROR.RELATIONSHIP.INVALID "You cannot
+     create a new version of the App in the current state". The decision
+     is TESTFLIGHT_ONLY: the build is stamped with the LOCKED version
+     string (so it joins that version's TestFlight train), the build
+     number still advances, and App Store metadata is skipped. Nothing
+     below runs and the project file is never touched.
+  3. Floor-check (non-strict): target >= combined floor across
      appStoreVersions + preReleaseVersions + builds->preReleaseVersion.
-  3. If the target row already exists in /appStoreVersions:
-       - any non-editable match (terminal/blocking) -> SystemExit(2);
-         the slot is taken by a shipped or in-review row.
+  4. If the target row already exists in /appStoreVersions:
+       - any terminal match -> auto-roll or SystemExit(2); the slot is
+         taken by a shipped row.
        - editable-only match -> REUSE its id (steady-state TestFlight
          iteration at unchanged MARKETING_VERSION).
-  4. CREATE path: floor-check (strict, target > floor); PATCH-rename any
+  5. CREATE path: floor-check (strict, target > floor); PATCH-rename any
      stale editable to target; or POST a new row.
 
 This module is intentionally thin: floor logic lives in
@@ -27,7 +37,9 @@ through this one so test patches at ``mmv.<seam>`` keep winning.
 
 Env: ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_PATH, APP_STORE_APPLE_ID,
      MARKETING_VERSION (project source of truth, set by action.yml).
-Stdout: {"decision":"REUSE|CREATE","versionString":"...","appStoreVersionId":"..."}
+Stdout: {"decision":"REUSE|CREATE|TESTFLIGHT_ONLY","versionString":"...",
+         "appStoreVersionId":"..."} -- TESTFLIGHT_ONLY carries an empty id,
+         the locked row's "state" and "storeVersionLocked" (== versionString).
 """
 
 from __future__ import annotations
@@ -67,6 +79,7 @@ from mmv_decide_create import (
 # working. The submodules look these up through this module at call
 # time, so a patch on ``mmv.fetch_versions`` propagates correctly.
 __all__ = (
+    "LOCKED_STATES",
     "SEM_RE",
     "create_or_reuse",
     "create_version",
@@ -78,8 +91,19 @@ __all__ = (
     "main",
     "make_jwt",
     "semver_tuple",
+    "store_version_locked",
 )
 
+#: App Store version states in which App Store Connect refuses to create or
+#: edit ANY version of the app -- the whole App Store slot is locked, not just
+#: the row itself. WAITING_FOR_REVIEW / IN_REVIEW: Apple is reviewing.
+#: PENDING_DEVELOPER_RELEASE: Apple approved and the developer has not
+#: released yet. A build made while one of these exists can only go to
+#: TestFlight (``TESTFLIGHT_ONLY``), and it goes under the locked version
+#: string so it lands in that version's TestFlight train instead of opening a
+#: new marketing-version train the floor logic would then have to roll past.
+LOCKED_STATES = frozenset(IN_REVIEW_STATES) | frozenset(BLOCKING_STATES)
+
 
 _APP_ID_MISSING_HINT = (
     "::error::APP_STORE_APPLE_ID is empty. This usually means auto-detect "
@@ -102,7 +126,8 @@ def _log(msg: str) -> None:
     print(f"[decision] {msg}", file=sys.stderr)
 
 
-def _result(decision: str, version: str, vid: str, state: str = "") -> dict:
+def _result(decision: str, version: str, vid: str, state: str = "",
+            **extra: str) -> dict:
     out = {
         "decision": decision,
         "versionString": version,
@@ -110,6 +135,7 @@ def _result(decision: str, version: str, vid: str, state: str = "") -> dict:
     }
     if state:
         out["state"] = state
+    out.update(extra)
     return out
 
 
@@ -284,20 +310,65 @@ def _auto_roll_past_locked(
     return rolled, new_status, new_match, new_also
 
 
+def store_version_locked(versions: list[dict]) -> dict | None:
+    """The ``TESTFLIGHT_ONLY`` decision when any App Store version locks the
+    slot (:data:`LOCKED_STATES`), else None.
+
+    Decided BEFORE the floor check and before any row at the target is
+    classified, because the lock is a property of the APP, not of the row at
+    the target: CI run 33743284641 (GoVolt) had 1.6.3 WAITING_FOR_REVIEW and a
+    project at 1.6.4, the target classified as "none", CREATE was attempted,
+    and App Store Connect answered 409 RELATIONSHIP.INVALID -- exit 4, every
+    push to main, until a human noticed. A target that itself matches the
+    in-review row used to exit 2 asking a human to wait or bump; that was a
+    person in the loop for a state the API describes precisely.
+
+    Several locked rows (Apple allows one per platform, but fail-safe): the
+    highest semver wins, because that is the train a new build belongs to.
+    Nothing here reads or writes the project file: the locked string is
+    exported for THIS build only and the project's MARKETING_VERSION stays the
+    source of truth for the next release.
+    """
+    locked = [v for v in versions if v.get("state") in LOCKED_STATES
+              and v.get("versionString")]
+    if not locked:
+        return None
+    row = max(locked, key=lambda v: semver_tuple(v["versionString"]))
+    version, state, vid = row["versionString"], row.get("state", ""), row.get("id", "")
+    _log(f"decision=TESTFLIGHT_ONLY versionString={version} (App Store version "
+         f"{version} is {state} (id={vid}); App Store Connect refuses to create "
+         f"or edit any version while one is in that state, so this build is "
+         f"stamped {version}, uploaded to TestFlight only, and App Store "
+         f"metadata is skipped)")
+    print(
+        f"::notice::App Store version {version} is {state}: uploading this build "
+        f"to TestFlight under {version} and skipping App Store metadata until "
+        f"Apple's review concludes.",
+        file=sys.stderr,
+    )
+    return _result("TESTFLIGHT_ONLY", version, "", state,
+                   storeVersionLocked=version)
+
+
 def decide_for_version(
     target_version: str, versions: list[dict],
     app_id: str, token: str,
 ) -> dict:
     """Find-or-create the ASC row at exactly ``target_version``.
 
-    Validates semver, runs the non-strict floor check (auto-bump
-    rewrites MARKETING_VERSION when below the ASC floor; the returned
-    effective target is what downstream uses), then classifies any
+    Validates semver, answers ``TESTFLIGHT_ONLY`` while any App Store
+    version locks the slot (:func:`store_version_locked` -- no floor check,
+    no auto-bump, no CREATE), then runs the non-strict floor check
+    (auto-bump rewrites MARKETING_VERSION when below the ASC floor; the
+    returned effective target is what downstream uses), then classifies any
     row(s) at target. Terminal collisions auto-roll to the next patch
-    (or reject when policy='none'); in-review and unknown-state
-    collisions reject loudly (see ``_classify_match_at_target`` for
-    the full taxonomy). No match -> CREATE; reusable editable -> REUSE."""
+    (or reject when policy='none'); unknown-state collisions reject loudly
+    (see ``_classify_match_at_target`` for the full taxonomy). No match ->
+    CREATE; reusable editable -> REUSE."""
     _validate_target(target_version)
+    locked = store_version_locked(versions)
+    if locked is not None:
+        return locked
     target_version = assert_target_meets_floor(
         target_version, app_id, token,
         appstore_versions=versions, strict=False,

package/action/scripts/test_action_step_order.py

@@ -0,0 +1,83 @@
+import re
+import unittest
+from pathlib import Path
+
+
+ACTION_YAML = Path(__file__).resolve().parents[1] / "action.yml"
+STEP_RE = re.compile(r"^    - name: (.+)$", re.M)
+
+
+def step_names(source: str) -> list[str]:
+    return [m.group(1).strip() for m in STEP_RE.finditer(source)]
+
+
+def step_block(source: str, name: str) -> str:
+    pattern = rf"    - name: {re.escape(name)}\n(?P<body>.*?)(?=\n    - name:|\Z)"
+    match = re.search(pattern, source, re.DOTALL)
+    if match is None:
+        raise AssertionError(f"missing action step: {name}")
+    return match.group("body")
+
+
+class TestActionStepOrder(unittest.TestCase):
+    """The plugin self-update runs before the steps that can fail a deploy,
+    lands in its own commit, and the run keeps reading ONE version of the
+    plugin from the snapshot it took first."""
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.source = ACTION_YAML.read_text(encoding="utf-8")
+        cls.names = step_names(cls.source)
+
+    def test_the_snapshot_is_the_first_step(self) -> None:
+        self.assertEqual(self.names[0], "Snapshot this action for the whole run")
+        block = step_block(self.source, "Snapshot this action for the whole run")
+        self.assertIn('cp -R "${{ github.action_path }}/." "$RUNNER_TEMP/swift-app-action/"', block)
+        self.assertIn('echo "SWIFT_APP_ACTION=$RUNNER_TEMP/swift-app-action" >> "$GITHUB_ENV"', block)
+
+    def test_the_autoupdate_and_its_commit_precede_the_version_step(self) -> None:
+        order = {name: index for index, name in enumerate(self.names)}
+        version = order["Resolve marketing version (project source of truth)"]
+        self.assertLess(order["Stage bot-side scripts to runner temp"], version)
+        self.assertLess(order["Check for app-ci update"], version)
+        self.assertLess(order["Commit + push refreshed app-ci"], version)
+        self.assertLess(order["Stage bot-side scripts to runner temp"],
+                        order["Check for app-ci update"])
+        self.assertLess(order["Check for app-ci update"],
+                        order["Commit + push refreshed app-ci"])
+        # ... and before every other step that talks to a store or signs.
+        for later in ("Resolve credentials + auto-detect Xcode project",
+                      "Stage ASC API key for xcrun / altool",
+                      "Prepare signing (cert + keychain + per-target profiles + pbxproj)",
+                      "Archive"):
+            self.assertLess(order["Commit + push refreshed app-ci"], order[later], later)
+
+    def test_the_autoupdate_commit_is_gated_like_the_check(self) -> None:
+        check = step_block(self.source, "Check for app-ci update")
+        commit = step_block(self.source, "Commit + push refreshed app-ci")
+        for block in (check, commit):
+            self.assertIn("inputs.auto-update == 'true'", block)
+            self.assertIn("github.event_name == 'push'", block)
+            self.assertIn("format('refs/heads/{0}', github.event.repository.default_branch)", block)
+        self.assertIn('bash "$BOT_SCRIPTS_DIR/commit_bot_changes.sh"', commit)
+        self.assertIn("GITHUB_REF_NAME: ${{ github.ref_name }}", commit)
+        # The cert refresh keeps its own, later commit step.
+        self.assertIn("Commit + push staged bot changes", self.names)
+        self.assertLess(self.names.index("Stage refreshed signing identity"),
+                        self.names.index("Commit + push staged bot changes"))
+
+    def test_every_script_and_prompt_is_read_from_the_snapshot(self) -> None:
+        lines = self.source.splitlines()
+        snapshot = step_block(self.source, "Snapshot this action for the whole run")
+        stray = [line for line in lines
+                 if "github.action_path" in line and line.strip() not in snapshot]
+        self.assertEqual(stray, [], "scripts must be read from $SWIFT_APP_ACTION")
+        self.assertGreaterEqual(self.source.count('"$SWIFT_APP_ACTION/scripts/'), 10)
+        self.assertEqual(self.source.count("${{ env.SWIFT_APP_ACTION }}/prompts/"), 2)
+        bot = step_block(self.source, "Stage bot-side scripts to runner temp")
+        self.assertIn('cp "$SWIFT_APP_ACTION/scripts/autoupdate_check.sh"', bot)
+        self.assertIn('cp "$SWIFT_APP_ACTION/scripts/commit_bot_changes.sh"', bot)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/action/scripts/test_manage_marketing_version_autoroll.py

@@ -4,11 +4,12 @@ Tests for the auto-roll-vs-in-review policy in
 ``manage_marketing_version.decide_for_version``.
 
 Round-7 codex finding lock-in: auto-roll fires for TERMINAL collisions
-(READY_FOR_SALE etc.) but NOT for in-review collisions
-(WAITING_FOR_REVIEW / IN_REVIEW). In-review must always reject so the
-developer can resolve the ambiguity manually -- Apple is actively
-reviewing the row, and advancing past it would race the review
-process.
+(READY_FOR_SALE etc.) but NEVER for in-review collisions
+(WAITING_FOR_REVIEW / IN_REVIEW / PENDING_DEVELOPER_RELEASE). Apple is
+reviewing (or holding) the row, and advancing past it would race the
+review process -- so those rows lock the App Store slot and the decision
+is TESTFLIGHT_ONLY, whatever the auto-bump policy: the build ships to
+TestFlight under the locked version and no project file is written.
 
 Extracted from ``test_manage_marketing_version.py`` so each test file
 stays under the 10-functions-per-file cap (round 8).
@@ -97,33 +98,40 @@ class AutoRollTerminalVsInReviewTests(unittest.TestCase):
         self.assertEqual(result["decision"], "CREATE")
         self.assertEqual(result["versionString"], "1.0.6")
 
-    def test_waiting_for_review_with_autobump_rejects_loudly(self):
-        """Round-7: in-review must NEVER auto-roll regardless of policy."""
+    def test_waiting_for_review_with_autobump_is_testflight_only(self):
+        """Round-7: in-review must NEVER auto-roll regardless of policy.
+        The slot is locked, so the build goes to TestFlight under the
+        locked version and the project file is left alone."""
         result, exit_code, stderr = self._run("WAITING_FOR_REVIEW", "patch")
-        self.assertIsNone(result)
-        self.assertEqual(exit_code, 2)
-        self.assertIn("currently in App Review", stderr)
+        self.assertIsNone(exit_code)
+        self.assertEqual(result["decision"], "TESTFLIGHT_ONLY")
+        self.assertEqual(result["versionString"], "1.0.5")
+        self.assertEqual(result["appStoreVersionId"], "")
+        self.assertIn("decision=TESTFLIGHT_ONLY", stderr)
+        self.assertNotIn("auto-bumped", stderr)
 
-    def test_in_review_with_autobump_rejects_loudly(self):
+    def test_in_review_with_autobump_is_testflight_only(self):
         result, exit_code, stderr = self._run("IN_REVIEW", "patch")
-        self.assertIsNone(result)
-        self.assertEqual(exit_code, 2)
-        self.assertIn("currently in App Review", stderr)
+        self.assertIsNone(exit_code)
+        self.assertEqual(result["decision"], "TESTFLIGHT_ONLY")
+        self.assertEqual(result["state"], "IN_REVIEW")
+        self.assertNotIn("auto-bumped", stderr)
 
-    def test_pending_developer_release_with_autobump_rejects_loudly(self):
+    def test_pending_developer_release_with_autobump_is_testflight_only(self):
         """Round-11: PENDING_DEVELOPER_RELEASE means Apple approved
         the build and is waiting on the developer's manual release
         click. Auto-rolling past it would bypass the developer's
         release decision -- silently shipping the next patch while
-        the approved build sits unreleased. Must reject loudly so a
-        human resolves the ambiguity."""
+        the approved build sits unreleased. The slot is locked the same
+        way a review locks it: TestFlight only, under 1.0.5."""
         result, exit_code, stderr = self._run(
             "PENDING_DEVELOPER_RELEASE", "patch",
         )
-        self.assertIsNone(result)
-        self.assertEqual(exit_code, 2)
+        self.assertIsNone(exit_code)
+        self.assertEqual(result["decision"], "TESTFLIGHT_ONLY")
+        self.assertEqual(result["versionString"], "1.0.5")
+        self.assertEqual(result["state"], "PENDING_DEVELOPER_RELEASE")
         self.assertIn("PENDING_DEVELOPER_RELEASE", stderr)
-        self.assertIn("manual release", stderr)
 
     def test_terminal_with_policy_none_rejects(self):
         result, exit_code, stderr = self._run("READY_FOR_SALE", "none")
@@ -131,11 +139,12 @@ class AutoRollTerminalVsInReviewTests(unittest.TestCase):
         self.assertEqual(exit_code, 2)
         self.assertIn("READY_FOR_SALE", stderr)
 
-    def test_in_review_with_policy_none_rejects(self):
+    def test_in_review_with_policy_none_is_testflight_only(self):
+        """The lock does not depend on the auto-bump policy at all."""
         result, exit_code, stderr = self._run("WAITING_FOR_REVIEW", "none")
-        self.assertIsNone(result)
-        self.assertEqual(exit_code, 2)
-        self.assertIn("currently in App Review", stderr)
+        self.assertIsNone(exit_code)
+        self.assertEqual(result["decision"], "TESTFLIGHT_ONLY")
+        self.assertIn("decision=TESTFLIGHT_ONLY", stderr)
 
     def test_editable_state_reuses_unchanged(self):
         """Sanity: PREPARE_FOR_SUBMISSION at target REUSEs unchanged."""

package/action/scripts/test_manage_marketing_version_match.py

@@ -9,9 +9,12 @@ doesn't match) an existing ASC row:
   * editable PFS at target -> REUSE
   * steady-state TestFlight (target == combined_floor with editable
     match) -> REUSE
-  * terminal / in-review collision at target -> SystemExit(2)
+  * terminal collision at target -> SystemExit(2)
     (the auto-roll lock-in test for terminal-but-autobump-enabled lives
     in test_manage_marketing_version_autoroll.py)
+  * in-review row at target -> TESTFLIGHT_ONLY (the App Store slot is
+    locked; the build goes to TestFlight under the locked version). The
+    sibling-in-review case lives in test_mmv_testflight_only.py.
   * DEVELOPER_REJECTED at target -> REUSE (developer pulled it from
     review; safe to mutate)
 
@@ -42,8 +45,8 @@ from tests_common import (  # noqa: E402
 def setUpModule() -> None:
     """Pin auto-bump to 'none' for the whole match-tests module.
 
-    The terminal-at-target / in-review-at-target tests assert the
-    historical SystemExit(2) reject behavior. With auto-bump enabled
+    The terminal-at-target tests assert the historical SystemExit(2)
+    reject behavior. With auto-bump enabled
     (the default 'patch'), the round-7 auto-roll would CREATE the
     next patch on TERMINAL collisions, which is a different code path
     covered by ``test_manage_marketing_version_autoroll.py``."""
@@ -139,35 +142,38 @@ class MatchAtTargetTests(unittest.TestCase):
         self.assertIn("fresh marketing version", stderr)
         _assert_mentions_build_setting_source(self, stderr)
 
-    def test_target_matches_waiting_for_review_exits_2(self):
-        """Issue 13: REUSE must NOT attach a TestFlight build to a
-        version Apple is reviewing. WAITING_FOR_REVIEW is editable in
-        ASC's broad sense, but mutating it would interfere with App
-        Review. SystemExit(2) with "review" wording."""
+    def test_target_matches_waiting_for_review_is_testflight_only(self):
+        """A version Apple is reviewing locks the whole App Store slot:
+        REUSE would attach a build to the row under review and CREATE
+        would 409. Neither a human wait nor a bump is asked for any
+        more -- the build goes to TestFlight under the locked version
+        (TESTFLIGHT_ONLY) with no App Store version id, and no
+        CREATE/REUSE seam is touched."""
         in_review = _v("1.0.0", "WAITING_FOR_REVIEW", vid="ed-wfr-100")
-        stderr = _assert_decide_exits(
-            self, "1.0.0", [in_review],
+        result, stderr, calls = _run_decide_for_version(
+            "1.0.0", versions=[in_review],
             ground_truth="1.0.0", combined_floor="1.0.0",
         )
-        self.assertIn("1.0.0", stderr)
-        self.assertIn("WAITING_FOR_REVIEW", stderr)
+        self.assertEqual(result["decision"], "TESTFLIGHT_ONLY")
+        self.assertEqual(result["versionString"], "1.0.0")
+        self.assertEqual(result["appStoreVersionId"], "")
+        self.assertEqual(result["state"], "WAITING_FOR_REVIEW")
+        self.assertEqual(result["storeVersionLocked"], "1.0.0")
+        self.assertEqual(calls, [])
+        self.assertIn("decision=TESTFLIGHT_ONLY", stderr)
         self.assertIn("ed-wfr-100", stderr)
-        self.assertIn("review", stderr.lower())
-        _assert_mentions_build_setting_source(self, stderr)
 
-    def test_target_matches_in_review_exits_2(self):
-        """Issue 13: IN_REVIEW match is also blocked, same as
-        WAITING_FOR_REVIEW. Apple is actively reviewing the row."""
+    def test_target_matches_in_review_is_testflight_only(self):
+        """IN_REVIEW locks the slot exactly as WAITING_FOR_REVIEW does."""
         in_review = _v("1.0.0", "IN_REVIEW", vid="ed-ir-100")
-        stderr = _assert_decide_exits(
-            self, "1.0.0", [in_review],
+        result, stderr, calls = _run_decide_for_version(
+            "1.0.0", versions=[in_review],
             ground_truth="1.0.0", combined_floor="1.0.0",
         )
-        self.assertIn("1.0.0", stderr)
-        self.assertIn("IN_REVIEW", stderr)
-        self.assertIn("ed-ir-100", stderr)
-        self.assertIn("review", stderr.lower())
-        _assert_mentions_build_setting_source(self, stderr)
+        self.assertEqual(result["decision"], "TESTFLIGHT_ONLY")
+        self.assertEqual(result["state"], "IN_REVIEW")
+        self.assertEqual(calls, [])
+        self.assertIn("decision=TESTFLIGHT_ONLY", stderr)
 
     def test_target_matches_developer_rejected_reuses(self):
         """Issue 13: DEVELOPER_REJECTED is in REUSABLE_STATES — the

package/action/scripts/test_mmv_decide_create.py

@@ -77,15 +77,17 @@ class StaleEditableSelectionTests(unittest.TestCase):
 
     def test_create_blocked_by_higher_editable_other_state(self):
         """Issue 10 covers every editable state, not just PFS. A draft
-        in WAITING_FOR_REVIEW above target must also block CREATE."""
-        higher = _v("1.2.0", "WAITING_FOR_REVIEW", vid="ed-wfr-120")
+        in METADATA_REJECTED above target must also block CREATE. (A
+        WAITING_FOR_REVIEW row locks the whole slot before this path is
+        reached -- see test_mmv_testflight_only.py.)"""
+        higher = _v("1.2.0", "METADATA_REJECTED", vid="ed-mr-120")
         stderr = _assert_decide_exits(
             self, "1.1.0", [higher], ground_truth=None,
         )
         self.assertIn("1.2.0", stderr)
-        self.assertIn("ed-wfr-120", stderr)
+        self.assertIn("ed-mr-120", stderr)
         self.assertIn("downgrade", stderr.lower())
-        self.assertIn("WAITING_FOR_REVIEW", stderr)
+        self.assertIn("METADATA_REJECTED", stderr)
 
     def test_create_blocked_by_equal_version_editable(self):
         """When an editable already sits at exactly target, REUSE wins
@@ -100,19 +102,23 @@ class StaleEditableSelectionTests(unittest.TestCase):
         self.assertEqual(calls, [])
         self.assertIn("decision=REUSE", stderr)
 
-    def test_lower_in_review_skipped_create_via_post(self):
+    def test_lower_in_review_is_never_patch_renamed(self):
         """Issue 13: a WAITING_FOR_REVIEW row at version < target must
-        NOT be PATCH-renamed (Apple is reviewing it). CREATE falls
-        through to a plain POST with stale_editable_id=None."""
+        NOT be PATCH-renamed (Apple is reviewing it). Two fences keep
+        that true: the slot lock answers TESTFLIGHT_ONLY before the
+        CREATE path is reached at all, and the CREATE path's own
+        stale-editable pick still skips in-review rows as a backstop."""
         in_review = _v("1.0.5", "WAITING_FOR_REVIEW", vid="ed-wfr-105")
         result, stderr, calls = _run_decide_for_version(
             "1.1.0", versions=[in_review], ground_truth="1.0.5",
         )
-        self.assertEqual(result["decision"], "CREATE")
-        self.assertEqual(result["versionString"], "1.1.0")
-        self.assertEqual(len(calls), 1)
-        self.assertIsNone(calls[0].kwargs.get("stale_editable_id"))
+        self.assertEqual(result["decision"], "TESTFLIGHT_ONLY")
+        self.assertEqual(result["versionString"], "1.0.5")
+        self.assertEqual(calls, [])
         self.assertNotIn("PATCH-rename", stderr)
+        import mmv_decide_create
+        self.assertIsNone(
+            mmv_decide_create._stale_editable_id([in_review], "1.1.0"))
 
 
 if __name__ == "__main__":

package/action/scripts/test_mmv_testflight_only.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+Tests for the ``TESTFLIGHT_ONLY`` decision of ``manage_marketing_version``.
+
+The incident this pins (GoVolt, CI run 33743284641, 2026-09-03): App Store
+version 1.6.3 sat WAITING_FOR_REVIEW while the project had moved to 1.6.4.
+The classifier looked only at rows AT the target, saw none, decided CREATE,
+and App Store Connect answered 409 ENTITY_ERROR.RELATIONSHIP.INVALID ("You
+cannot create a new version of the App in the current state") -- exit 4 on
+every push to main until a person noticed. A target that itself matched the
+in-review row used to exit 2 asking a human to wait or bump.
+
+Both are the same fact about the APP: while any version is under review (or
+approved and awaiting the developer's release click) the whole App Store slot
+is locked. The decision is now ``TESTFLIGHT_ONLY``: stamp the locked version
+string, take the next build number, upload to TestFlight, skip App Store
+metadata, and never touch the project file.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import sys
+import unittest
+from contextlib import redirect_stderr
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import manage_marketing_version as mmv  # noqa: E402
+
+from tests_common import _run_decide_for_version, _v  # noqa: E402
+
+
+def _boom(*_args, **_kwargs):
+    raise AssertionError("a seam ran on the TESTFLIGHT_ONLY path")
+
+
+class TestFlightOnlyTests(unittest.TestCase):
+    """Any locked App Store version -> TESTFLIGHT_ONLY, nothing else runs."""
+
+    def _decide(self, target: str, versions: list[dict]):
+        """Run ``decide_for_version`` with every floor/create seam armed to
+        raise, so the test proves the lock is decided before any of them."""
+        buf = io.StringIO()
+        with mock.patch.object(mmv, "assert_target_meets_floor", _boom), \
+                mock.patch.object(mmv, "decide_create", _boom), \
+                mock.patch.object(mmv, "create_or_reuse_with_stale", _boom), \
+                mock.patch.object(mmv, "get_combined_floor", _boom), \
+                mock.patch.object(mmv, "get_ground_truth_floor", _boom), \
+                mock.patch.object(mmv, "maybe_auto_bump", _boom), \
+                redirect_stderr(buf):
+            result = mmv.decide_for_version(
+                target, versions, app_id="111", token="tok",
+            )
+        return result, buf.getvalue()
+
+    def test_sibling_in_review_is_testflight_only_under_the_sibling(self):
+        """The incident shape: project at 1.6.4, 1.6.3 WAITING_FOR_REVIEW.
+        The build is stamped 1.6.3 -- the locked version -- not 1.6.4."""
+        versions = [
+            _v("1.6.2", "READY_FOR_SALE", vid="rfs-162"),
+            _v("1.6.3", "WAITING_FOR_REVIEW", vid="wfr-163"),
+        ]
+        result, stderr = self._decide("1.6.4", versions)
+        self.assertEqual(result, {
+            "decision": "TESTFLIGHT_ONLY",
+            "versionString": "1.6.3",
+            "appStoreVersionId": "",
+            "state": "WAITING_FOR_REVIEW",
+            "storeVersionLocked": "1.6.3",
+        })
+        self.assertIn("decision=TESTFLIGHT_ONLY versionString=1.6.3", stderr)
+        self.assertIn("wfr-163", stderr)
+        self.assertIn("::notice::", stderr)
+
+    def test_target_equal_to_the_in_review_row_is_testflight_only(self):
+        result, _ = self._decide("1.6.3", [_v("1.6.3", "IN_REVIEW", vid="ir")])
+        self.assertEqual(result["decision"], "TESTFLIGHT_ONLY")
+        self.assertEqual(result["versionString"], "1.6.3")
+        self.assertEqual(result["state"], "IN_REVIEW")
+
+    def test_pending_developer_release_locks_the_slot_too(self):
+        """Apple approved 1.6.3 and the developer has not released it: a
+        new App Store version cannot be created either."""
+        result, _ = self._decide(
+            "1.6.4", [_v("1.6.3", "PENDING_DEVELOPER_RELEASE", vid="pdr")])
+        self.assertEqual(result["decision"], "TESTFLIGHT_ONLY")
+        self.assertEqual(result["versionString"], "1.6.3")
+        self.assertEqual(result["state"], "PENDING_DEVELOPER_RELEASE")
+
+    def test_several_locked_rows_pick_the_highest_semver(self):
+        versions = [
+            _v("1.6.3", "PENDING_DEVELOPER_RELEASE", vid="pdr-163"),
+            _v("1.6.10", "WAITING_FOR_REVIEW", vid="wfr-1610"),
+            _v("1.6.9", "IN_REVIEW", vid="ir-169"),
+        ]
+        result, _ = self._decide("1.7.0", versions)
+        self.assertEqual(result["versionString"], "1.6.10")
+        self.assertEqual(result["storeVersionLocked"], "1.6.10")
+
+    def test_nothing_in_review_leaves_the_ordinary_path_untouched(self):
+        """Editable / terminal / archived rows do not lock the slot: the
+        ordinary floor + classify path runs and CREATEs as before."""
+        versions = [
+            _v("1.6.2", "READY_FOR_SALE", vid="rfs-162"),
+            _v("1.6.0", "REPLACED_WITH_NEW_VERSION", vid="old"),
+            _v("1.6.1", "DEVELOPER_REJECTED", vid="dr"),
+        ]
+        result, stderr, calls = _run_decide_for_version(
+            "1.6.4", versions=versions, ground_truth="1.6.2",
+        )
+        self.assertEqual(result["decision"], "CREATE")
+        self.assertEqual(result["versionString"], "1.6.4")
+        self.assertNotIn("storeVersionLocked", result)
+        self.assertEqual(len(calls), 1)
+        self.assertNotIn("TESTFLIGHT_ONLY", stderr)
+        self.assertIsNone(mmv.store_version_locked(versions))
+
+    def test_main_prints_the_locked_decision_as_json(self):
+        """End to end through ``main()``: the JSON action.yml parses."""
+        out_buf, err_buf = io.StringIO(), io.StringIO()
+        env = {
+            "ASC_KEY_ID": "kid", "ASC_ISSUER_ID": "iid",
+            "ASC_KEY_PATH": "/tmp/ignored.p8", "APP_STORE_APPLE_ID": "111",
+            "MARKETING_VERSION": "1.6.4",
+        }
+        rows = [_v("1.6.3", "WAITING_FOR_REVIEW", vid="wfr-163")]
+        with mock.patch.dict(os.environ, env, clear=False), \
+                mock.patch.object(mmv, "make_jwt", return_value="tok"), \
+                mock.patch.object(mmv, "fetch_versions", return_value=rows), \
+                mock.patch.object(mmv, "assert_target_meets_floor", _boom), \
+                mock.patch("sys.stdout", out_buf), \
+                redirect_stderr(err_buf):
+            mmv.main()
+        decision = json.loads(out_buf.getvalue().strip())
+        self.assertEqual(decision["decision"], "TESTFLIGHT_ONLY")
+        self.assertEqual(decision["versionString"], "1.6.3")
+        self.assertEqual(decision["appStoreVersionId"], "")
+        self.assertEqual(decision["storeVersionLocked"], "1.6.3")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/action/scripts/test_testflight_version_slot_wiring.py

@@ -45,6 +45,31 @@ class TestTestFlightVersionSlotWiring(unittest.TestCase):
         self.assertIn("inputs.manage-app-store-version == 'true'", detector)
         self.assertIn("inputs.manage-app-store-version == 'true'", whats_new)
 
+    def test_a_locked_store_version_ships_testflight_only(self) -> None:
+        """The TESTFLIGHT_ONLY decision: the locked version is re-exported
+        as MARKETING_VERSION (the build joins that train), no App Store
+        version id is set, STORE_VERSION_LOCKED gates the metadata
+        writers off, and the typed annotation carries the schema the
+        panel parses."""
+        store_slot = step_block(self.source, "Resolve App Store version slot (REUSE or CREATE)")
+        self.assertIn('if [ "$DECISION" = "TESTFLIGHT_ONLY" ]; then', store_slot)
+        self.assertIn('echo "STORE_VERSION_LOCKED=$EFFECTIVE_MV" >> "$GITHUB_ENV"', store_slot)
+        self.assertIn('::notice title=store_version_locked::', store_slot)
+        self.assertIn('\\"schema\\":\\"gowalk-cicd/store-version-locked.v1\\"', store_slot)
+        for field in ("version", "state", "build_number"):
+            self.assertIn(f'\\"{field}\\":', store_slot)
+        # The locked branch re-exports MARKETING_VERSION exactly as the
+        # auto-bump branch does, so Stamp Info.plist and Archive read it.
+        locked = store_slot.split('if [ "$DECISION" = "TESTFLIGHT_ONLY" ]; then', 1)[1]
+        locked = locked.split("elif", 1)[0]
+        self.assertIn('echo "MARKETING_VERSION=$EFFECTIVE_MV" >> "$GITHUB_ENV"', locked)
+        # Neither metadata writer runs against a locked slot: both scripts
+        # require APP_STORE_VERSION_ID, which is empty here.
+        detector = step_block(self.source, "Detect empty ASC metadata fields")
+        whats_new = step_block(self.source, 'Set App Store "What\'s New"')
+        self.assertIn("env.STORE_VERSION_LOCKED == ''", detector)
+        self.assertIn("env.STORE_VERSION_LOCKED == ''", whats_new)
+
 
 if __name__ == "__main__":
     unittest.main()

package/android-action/.daemux-version

@@ -1 +1 @@
-1.0.52
+1.0.53

package/backend-action/.daemux-version

@@ -1 +1 @@
-1.0.52
+1.0.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gowalk-cicd",
-  "version": "1.0.52",
+  "version": "1.0.53",
   "description": "Zero-config GitHub Actions delivery for iOS TestFlight and Android Google Play.",
   "type": "module",
   "bin": {

package/templates/deploy.yml

@@ -453,14 +453,21 @@ jobs:
             ${{ hashFiles('distribution/whatsnew/**') != '' && 'distribution/whatsnew' || '' }}
           changesNotSentForReview: true
 
-      - name: Say what still needs a human
+      # The retry landed the bundle without submitting it. That is a fact for
+      # the panel that merged this commit, not a chore for a person: the panel
+      # reads this typed check-run annotation off the job (title + JSON with a
+      # versioned schema, never the log text) and opens its own Play console
+      # step that presses "Send changes for review". Normal after a policy
+      # rejection; the ordinary first upload submits and this never fires.
+      - name: Record that Play holds this release for a review submission
         if: ${{ always() && steps.play-upload-retry.outcome == 'success' }}
         shell: bash
+        env:
+          PACKAGE: ${{ steps.android.outputs.package-name }}
+          TRACK: ${{ vars.GOOGLE_PLAY_TRACK || 'internal' }}
+          VERSION_CODE: ${{ steps.android.outputs.build-number }}
         run: |
-          echo "::warning::Play would not accept this release for review automatically, so it was \
-          uploaded without being submitted. Open Play Console for \
-          ${{ steps.android.outputs.package-name }} and press 'Send changes for review' on the \
-          Publishing overview page. This is normal after a policy rejection."
+          echo "::notice title=play_review_pending::{\"schema\":\"gowalk-cicd/play-review-pending.v1\",\"package\":\"${PACKAGE}\",\"track\":\"${TRACK}\",\"version_code\":\"${VERSION_CODE}\"}"
 
   # GitHub only registers a newly added workflow after it reaches the default
   # branch. A brand-new app's feature branch therefore cannot dispatch the