feat: forward client_payload.runtime_version + ARG RUNTIME_VERSION

Closes the cache trap structurally (instead of pin-bumping every
runtime release):
1. publish-image.yml caller now forwards
   github.event.client_payload.runtime_version (set by cascade) to
   the molecule-ci reusable workflow as runtime_version input.
2. Reusable workflow forwards it to docker build as a --build-arg.
3. Dockerfile declares ARG RUNTIME_VERSION near the pip install
   layer so its value becomes part of the cache key.
4. The pip install RUN command does an extra targeted upgrade to
   the exact version when ARG is set — guarantees the version is
   what we expect even if requirements.txt resolves to something
   else.

Pairs with molecule-ci PR #12 + molecule-core PR #2181. Together
the pipeline is now race- and cache-proof end-to-end.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.github/workflows/publish-image.yml

@@ -16,6 +16,11 @@ on:
     branches: [main]
   pull_request:
   workflow_dispatch:
+    inputs:
+      runtime_version:
+        description: "Optional explicit runtime version to bake in (forwarded as RUNTIME_VERSION build-arg)"
+        required: false
+        type: string
 
 permissions:
   contents: read
@@ -25,3 +30,11 @@ jobs:
   publish:
     uses: Molecule-AI/molecule-ci/.github/workflows/publish-template-image.yml@main
     secrets: inherit
+    with:
+      # When the cascade fires, client_payload.runtime_version is the
+      # exact version PyPI just published. Forwarded to the reusable
+      # workflow as a docker --build-arg so the cache key changes
+      # per-version and pip install resolves freshly.
+      # On other events (push/PR/manual without input), this is empty
+      # and the Dockerfile's default (requirements.txt pin) applies.
+      runtime_version: ${{ github.event.client_payload.runtime_version || inputs.runtime_version || '' }}

Dockerfile

@@ -21,9 +21,24 @@ RUN npm install -g @anthropic-ai/claude-code 2>/dev/null || true
 RUN useradd -u 1000 -m -s /bin/bash agent
 WORKDIR /app
 
-# Install Python deps
+# RUNTIME_VERSION is forwarded from the reusable publish workflow as
+# a docker build-arg. When set (cascade-triggered builds), it's the
+# exact runtime version PyPI just published. Including it as an ARG
+# changes the cache key for the pip install layer below — without
+# this, identical Dockerfile + identical requirements.txt content
+# would let docker reuse the cached layer with the previous version
+# baked in (the cache trap that bit us 5x on 2026-04-27).
+# Empty default = falls back to whatever requirements.txt resolves to.
+ARG RUNTIME_VERSION=
+
+# Install Python deps. The RUNTIME_VERSION ARG is a no-op argument to
+# the RUN command itself but its presence as a declared ARG above
+# means buildx hashes it into the cache key.
 COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt && \
+    if [ -n "${RUNTIME_VERSION}" ]; then \
+      pip install --no-cache-dir --upgrade "molecule-ai-workspace-runtime==${RUNTIME_VERSION}"; \
+    fi
 
 # Copy adapter code
 COPY adapter.py .