@@ -83,6 +83,22 @@ jobs:
       line: ${{ steps.parse.outputs.line }}
       e2e_verification: ${{ steps.e2e-gate.outputs.verification || steps.e2e-bypass.outputs.verification }}
     steps:
+      # A dispatch runs the copy of this workflow at the ref it was dispatched
+      # from, so a dispatch from release-X.Y runs that branch's older copy (on
+      # 2026-10-16 one job instead of five) and, now that release assets are
+      # signed, would fail at the upload step after the staging branch, the
+      # promotion-* candidate and the draft already exist. docs/release.md also
+      # pins the signature identity to this workflow on main. Refuse anything
+      # else here, before the first write.
+      - name: Refuse a dispatch from any ref but main
+        env:
+          REF: ${{ github.ref }}
+        run: |
+          if [ "$REF" != "refs/heads/main" ]; then
+            echo "::error::Promote RC must be dispatched from 'main' (got '$REF'); pick 'main' as the branch and let rc_tag choose the line."
+            exit 1
+          fi
+
       # Validate the dispatch input against a strict rc pattern before it ever
       # reaches a shell or an API call. Derives the stable version, the rc
       # staging branch, and the maintenance line.
 
@@ -73,7 +73,7 @@ A regular release sequence runs as follows:
        commit id: "cherry-picked fix" tag: "v1.2.0-rc.2"
    ```
 
-3. Once the checks are green, run the [`promote-rc.yaml`](../.github/workflows/promote-rc.yaml) workflow (manual dispatch **from `main`**, the only branch it is dispatched from, whichever line the rc belongs to) with that rc tag. Its `parse` job verifies E2E before any staging: it accepts a successful `rc-e2e` job in the latest `tags.yaml` push run for the tag, or any retained successful manual `e2e-tag.yaml` run whose expanded E2E job name targets the tag. The emergency `skip_e2e_gate` input bypasses this check, logs a loud warning, and marks the promote PR with ⚠️. Before its first registry write, promotion also proves that the selected `main` or `release-X.Y` target already contains the candidate-aware PR gate, finalizer and trusted verifier; backport this pipeline to an existing maintenance branch before promoting its next patch. Promotion **creates no stable name before merge**: dispatch does write to the registry — it publishes one `promotion-*` packages candidate, and that tag is real and publicly listable — but it creates no `vX.Y.Z` tag, moves no `latest`, and publishes no stable installer, so nothing a consumer resolves changes until the PR merges. It:
+3. Once the checks are green, run the [`promote-rc.yaml`](../.github/workflows/promote-rc.yaml) workflow (manual dispatch **from `main`**, the only branch it is dispatched from, whichever line the rc belongs to; its `parse` job refuses any other ref before anything is written) with that rc tag. Its `parse` job verifies E2E before any staging: it accepts a successful `rc-e2e` job in the latest `tags.yaml` push run for the tag, or any retained successful manual `e2e-tag.yaml` run whose expanded E2E job name targets the tag. The emergency `skip_e2e_gate` input bypasses this check, logs a loud warning, and marks the promote PR with ⚠️. Before its first registry write, promotion also proves that the selected `main` or `release-X.Y` target already contains the candidate-aware PR gate, finalizer and trusted verifier; backport this pipeline to an existing maintenance branch before promoting its next patch. Promotion **creates no stable name before merge**: dispatch does write to the registry — it publishes one `promotion-*` packages candidate, and that tag is real and publicly listable — but it creates no `vX.Y.Z` tag, moves no `latest`, and publishes no stable installer, so nothing a consumer resolves changes until the PR merges. It:
    1. Rewrites the rc version substring to `1.2.0` and commits that exact tree, serializes its `packages/` directory under a run-specific temporary OCI tag, then adds a second commit pinning the candidate's immutable digest in the installer before pushing `release-1.2.0`. Container digests remain exactly the rc's; the two commits give the OCI revision an honest source SHA without pretending the artifact can contain its own digest.
    2. Drafts the `v1.2.0` release and uploads the (restamped) assets.
    3. Generates `docs/changelogs/v1.2.0.md` (in a parallel job, detached at the rc tag) — or, if you pressed the rc-time `Generate RC Changelog` button, copies the file already banked on the `release-1.2.0-rc.N` staging branch instead of regenerating — and commits it onto the `release-1.2.0` branch, so the changelog is reviewed as part of the promotion and finalize can publish the release with it already in place. Non-blocking: if generation fails the PR still opens, carrying a ⚠️ line that says the changelog is missing.
 
@@ -0,0 +1,40 @@
+#!/usr/bin/env bats
+# promote-rc.yaml is dispatched from main only: a dispatch from another ref
+# runs that ref's copy of the workflow, and the release signature names main
+# as the identity. The refuse step has to be the first thing parse does, so a
+# wrong dispatch fails before the staging branch, the promotion-* candidate or
+# the draft release exist.
+#
+# Run with: bats hack/promote-rc-dispatch-ref_test.bats
+
+load test_helper
+
+REPO_ROOT="$(cd "$(dirname "${BATS_TEST_FILENAME:-$0}")/.." && pwd)"
+WF="$REPO_ROOT/.github/workflows/promote-rc.yaml"
+STEP_NAME="Refuse a dispatch from any ref but main"
+
+_step_run() {
+  yq ".jobs.parse.steps[] | select(.name == \"$STEP_NAME\").run" "$WF"
+}
+
+@test "the refuse step is the first step of parse and reads github.ref" {
+  [ "$(yq '.jobs.parse.steps[0].name' "$WF")" = "$STEP_NAME" ]
+  [ "$(yq '.jobs.parse.steps[0].env.REF' "$WF")" = '${{ github.ref }}' ]
+}
+
+@test "a dispatch from main passes" {
+  step="$(_step_run)"
+  [ -n "$step" ]
+  run env REF=refs/heads/main dash -c "$step"
+  [ "$status" -eq 0 ]
+}
+
+@test "a dispatch from a release branch or a tag fails and names main" {
+  step="$(_step_run)"
+  for ref in refs/heads/release-1.7 refs/tags/v1.7.0-rc.3 ""; do
+    run env REF="$ref" dash -c "$step"
+    [ "$status" -ne 0 ]
+    printf '%s\n' "$output" | grep -qF "::error::"
+    printf '%s\n' "$output" | grep -qF "from 'main'"
+  done
+}