CI: build with the beta crafter-build Flatpak, chosen through CRAFTER_REF

Run 533, the first on the Flatpak toolchain, installed the Flatpak, built
the server and passed all 28 suites, then failed building the wasm bundle:
Crafter.Graphics master has used the Shader `defines` and `variant` fields
since 2026-10-06, and the `stable` Flatpak is the 2.1.0 release from three
days before that. Only Crafter.Build master has them, so the toolchain is
its `beta` branch for now, which is also what the rolling `latest` tarball
this job used to download was: a build of master.

The branch is one variable at the top of the job, the way imsd's package
job pins its own (imsd stays on stable; it has no Crafter.Graphics). Flip
it back to //stable once a Crafter.Build release carries the fields. The
wrapper scripts expand the ref at write time, and the install step prints
them along with the Flatpak's branch and commit so a run's log says which
toolchain it used.

Verified locally with beta 2.1.0-10-g4af9280: the wasm bundle builds and
the server suite passes, except ShouldServePostPages, which needs the media
mirror on the deploy mount that only exists in CI.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

.forgejo/workflows/deploy.yaml

@@ -22,6 +22,16 @@ jobs:
     # and its Sdk between runs. Same route as imsd's package job; see
     # deploy/README.md "Runner configuration".
     runs-on: flatpak
+    env:
+      # Which crafter-build. `stable` is the branch Crafter.Build publishes
+      # from its release tags, `beta` follows every push to its master (the
+      # same thing the rolling `latest` tarball this job used to download
+      # was). This site tracks Crafter.Graphics master, which since 2026-10-06
+      # uses the Shader `defines`/`variant` fields that only Crafter.Build
+      # master has: the 2.1.0 release predates them by three days, and run
+      # 533 failed on exactly that. Flip to //stable once a Crafter.Build
+      # release carries them. imsd pins stable; it has no Crafter.Graphics.
+      CRAFTER_REF: net.catcrafts.CrafterBuild//beta
     steps:
       - name: Check live payment test credentials
         # ShouldSettleEurcOnTestnet is a mandatory deploy gate, so a missing
@@ -85,24 +95,24 @@ jobs:
         # crafter-build is the Crafter.Build Flatpak, the route imsd's package
         # job takes: it carries its own clang, lld, libc++ and WASI sysroot, and
         # its Sdk (org.freedesktop.Sdk, from Flathub) has the cmake, make, perl,
-        # git, gpg and OpenSSL the build and the suites need. `stable` is the
-        # branch Crafter.Build publishes from its release tags (`beta` follows
-        # every push to its master), so the toolchain moves only with a release
-        # of the toolchain. Crafter.Build's CI publishes the Flatpak and nothing
-        # else since 2026-10-02: the rolling `latest` release's
-        # crafter-build-linux-x86_64-v2.tar.gz this step used to download is
-        # gone (404), which is what failed the deploy on 2026-10-12.
+        # git, gpg and OpenSSL the build and the suites need. The branch is
+        # CRAFTER_REF at the top of the job. Crafter.Build's CI publishes the
+        # Flatpak and nothing else since 2026-10-02: the rolling `latest`
+        # release's crafter-build-linux-x86_64-v2.tar.gz this step used to
+        # download is gone (404), which is what failed the deploy on
+        # 2026-10-12.
         #
         # /var/lib/flatpak is a docker volume the runner mounts, so the Sdk and
         # the Flatpak (about 4 GB on disk) are downloaded once; `install` is a
-        # no-op after that and `update` follows new stable releases. The install is retried: a
-        # flaky download must not fail a deploy before any build time is spent.
+        # no-op after that and `update` moves the installed branch forward.
+        # The install is retried: a flaky download must not fail a deploy
+        # before any build time is spent.
         run: |
           set -eu
           flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
           flatpak remote-add --if-not-exists catcrafts https://flatpak.catcrafts.net/catcrafts.flatpakrepo
           for i in 1 2 3; do
-            flatpak install -y --noninteractive catcrafts net.catcrafts.CrafterBuild//stable && break
+            flatpak install -y --noninteractive catcrafts "$CRAFTER_REF" && break
             if [ "$i" -eq 3 ]; then
               echo "ERROR: installing the crafter-build Flatpak failed 3 times." >&2
               exit 1
@@ -117,9 +127,9 @@ jobs:
           # sandbox and ShouldSettleEurcOnTestnet shells out to cast, which
           # the next step installs there: the sandbox sees the host's /opt but
           # not its /usr/local.
-          cat > /usr/local/bin/crafter-build <<'EOF'
+          cat > /usr/local/bin/crafter-build <<EOF
           #!/bin/sh
-          exec flatpak run --env=PATH=/app/bin:/usr/bin:/opt/foundry/bin net.catcrafts.CrafterBuild//stable "$@"
+          exec flatpak run --env=PATH=/app/bin:/usr/bin:/opt/foundry/bin $CRAFTER_REF "\$@"
           EOF
           # A binary crafter-build builds for the host links the Flatpak's
           # libc++ (and the Sdk's glibc, newer than this container's), so it
@@ -127,15 +137,16 @@ jobs:
           # <args>` is how the steps below call catcrafts-server. The host
           # itself gets those libraries shipped next to the binary, see
           # "Deploy backend".
-          cat > /usr/local/bin/crafter-run <<'EOF'
+          cat > /usr/local/bin/crafter-run <<EOF
           #!/bin/sh
-          cmd=$1; shift
-          case $cmd in /*) ;; *) cmd=$PWD/$cmd ;; esac
-          exec flatpak run --env=PATH=/app/bin:/usr/bin:/opt/foundry/bin --command="$cmd" net.catcrafts.CrafterBuild//stable "$@"
+          cmd=\$1; shift
+          case \$cmd in /*) ;; *) cmd=\$PWD/\$cmd ;; esac
+          exec flatpak run --env=PATH=/app/bin:/usr/bin:/opt/foundry/bin --command="\$cmd" $CRAFTER_REF "\$@"
           EOF
           chmod +x /usr/local/bin/crafter-build /usr/local/bin/crafter-run
-          flatpak info net.catcrafts.CrafterBuild//stable | sed -n 's/^ *\(Version\|Commit\|Date\): */crafter-build \1: /p'
+          flatpak info "$CRAFTER_REF" | sed -n 's/^ *\(Version\|Commit\|Date\|Branch\): */crafter-build \1: /p'
           crafter-build --version
+          cat /usr/local/bin/crafter-build /usr/local/bin/crafter-run
 
       - name: Install cast (Foundry)
         # The ShouldSettleEurcOnTestnet gate pays its own test order with a
@@ -457,7 +468,7 @@ jobs:
           # more than GLIBC_2.38 from the host's glibc (checked with objdump -T
           # on 2026-10-12; the Sdk's own glibc is newer than the host's, which
           # is why it matters).
-          APP=$(flatpak info --show-location net.catcrafts.CrafterBuild//stable)/files/lib
+          APP=$(flatpak info --show-location "$CRAFTER_REF")/files/lib
           for lib in libc++.so.1 libc++abi.so.1 libunwind.so.1; do
             if [ ! -f "$APP/$lib" ]; then
               echo "ERROR: $lib not found in the crafter-build Flatpak under $APP." >&2

deploy/README.md

@@ -1038,6 +1038,16 @@ host's. Where the host has no matching libc++, run the binary inside the
 sandbox, which is what CI's `crafter-run` wrapper does:
 `flatpak run --command=$PWD/<server>/catcrafts-server net.catcrafts.CrafterBuild --routes`.
 
+Which branch of the Flatpak CI builds with is `CRAFTER_REF` at the top of
+`.forgejo/workflows/deploy.yaml`. `stable` is published from Crafter.Build's
+release tags, `beta` from every push to its master. The site tracks
+Crafter.Graphics master, and since 2026-10-06 that uses Shader fields that
+only Crafter.Build master has, so CI is on `beta` until a release carries
+them (`flatpak run --command=sh net.catcrafts.CrafterBuild//beta -c
+'crafter-build --version'` prints which master commit a beta is). Note that
+`flatpak install` of an already-installed ref is a no-op even when the remote
+has moved on; `flatpak update` is what moves it, and the workflow runs both.
+
 ### If a `bin/` glob matches two directories
 
 The variant directory name embeds a config hash, and **`` and