@@ -1,27 +1,51 @@
 name: "Setup OpenClaw"
-description: "Install OpenClaw (Node CLI) globally and expose it on PATH for downstream E2E steps."
+description: "Install the pinned OpenClaw (Node CLI) and expose it on PATH for downstream E2E steps."
 
 # Why npm and not pip:
-#   OpenClaw is published to npm as `openclaw` (Node 22.16+).
+#   OpenClaw is published to npm as `openclaw`.
 #   The PyPI package named `openclaw` is an unrelated CMDOP plugin.
 #   See: https://github.com/openclaw/openclaw
 #
 # Why a composite action:
 #   Multiple workflows (pr-screenshots, e2e-nightly, openclaw-boot, future
 #   real-data tests) need a working `openclaw` on PATH. Centralising the
-#   install lets us bump the pin once and cache per-runner.
+#   install lets us move the pin once, in one place.
+
+# The installed openclaw version is not an input. It is pinned in this
+# directory's package.json and package-lock.json, so `npm ci` installs exactly
+# the recorded tree and checks every tarball against its integrity hash. An
+# upgrade is a Dependabot pull request against that lockfile, not a dist-tag
+# resolved fresh on each run.
+#
+# Why the pin is 2026.5.12 and not the newest release:
+#   `latest` was never actually resolved on a run. The actions/cache step this
+#   action used to carry was keyed on the literal string "latest", so the key
+#   never changed and never invalidated; every job since May restored that
+#   cache and logged "openclaw cache hit, skipping install". CI has therefore
+#   been testing against 2026.5.12 for months while appearing to track latest.
+#   2026.5.12 is what the E2E suites are green against today, so pinning it
+#   here is a no-op for behaviour and confines this change to the supply-chain
+#   fix. Moving off it is real work, not a version bump — see the note on the
+#   Dependabot entry in .github/dependabot.yml.
+#
+# The mirror of this action in vivekchand/clawmetry-cloud (cloud #2300) pins
+# 2026.9.2, deliberately not the same version. Cloud has no live-OpenClaw
+# transcript E2E, so the JSONL/SQLite boundary described above does not reach
+# it. The two copies share a mechanism, not a version; keep them in step on the
+# mechanism and let each pin what its own suites are green against.
 
 inputs:
-  version:
-    description: "openclaw npm dist-tag or version (e.g. latest, beta, 2026.5.12)"
-    required: false
-    default: "latest"
   gateway-token:
     description: "Value to export as OPENCLAW_GATEWAY_TOKEN for downstream steps."
     required: false
     default: "ci-openclaw-token"
   node-version:
-    description: "Node major to install. OpenClaw requires Node 22.16+."
+    description: >-
+      Node major to install. The pinned openclaw 2026.5.12 declares
+      `>=22.16.0`, so the default names the major and lets setup-node resolve
+      the newest 22.x. Newer openclaw releases enforce a much narrower range in
+      their own install script rather than only warning, so a Dependabot bump
+      is what would make this need changing.
     required: false
     default: "22"
 
@@ -36,47 +60,40 @@ outputs:
 runs:
   using: "composite"
   steps:
+    # The hand-rolled actions/cache step this action used to carry is gone with
+    # the dist-tag it keyed on. setup-node's own `cache: npm` is deliberately
+    # NOT enabled in its place: its `cache-dependency-path` is resolved against
+    # the workspace root, and pr-screenshots.yml checks this repository out
+    # under `head/`, where that path matches no file and the step fails. The
+    # install is a few seconds either way; correctness on every caller is worth
+    # more than the cache.
     - name: Setup Node
       uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
       with:
         node-version: ${{ inputs.node-version }}
 
-    # Cache the global npm prefix so repeat runs skip the network fetch.
-    # Keyed on (OS, requested version) so a version bump invalidates cleanly.
-    - name: Cache global openclaw install
-      id: cache
-      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
-      with:
-        path: |
-          ~/.npm-openclaw-global
-        key: openclaw-${{ runner.os }}-${{ inputs.version }}-v1
-
-    # `version` is supplied by the calling workflow, so it reaches the shell
-    # through the environment and is referenced as a quoted variable rather
-    # than being expanded into the script text by the expression evaluator.
-    - name: Install OpenClaw (npm -g)
+    # `npm ci` installs the tree recorded in package-lock.json and nothing else:
+    # no re-resolution against the registry's moving tags, and every tarball is
+    # checked against its sha512 integrity hash. `--prefix` is what lets the
+    # step run from the caller's working directory while installing into this
+    # action's own directory.
+    - name: Install OpenClaw (npm ci from the pinned lockfile)
       shell: bash
       env:
-        OPENCLAW_VERSION: ${{ inputs.version }}
-        OPENCLAW_CACHE_HIT: ${{ steps.cache.outputs.cache-hit }}
+        ACTION_DIR: ${{ github.action_path }}
       run: |
         set -e
-        PREFIX="$HOME/.npm-openclaw-global"
-        mkdir -p "$PREFIX"
-        npm config set prefix "$PREFIX"
-        echo "$PREFIX/bin" >> "$GITHUB_PATH"
-        if [ "$OPENCLAW_CACHE_HIT" = "true" ] && [ -x "$PREFIX/bin/openclaw" ]; then
-          echo "openclaw cache hit, skipping install"
-        else
-          npm install -g --no-audit --no-fund "openclaw@$OPENCLAW_VERSION"
-        fi
+        npm ci --no-audit --no-fund --prefix "$ACTION_DIR"
+        echo "$ACTION_DIR/node_modules/.bin" >> "$GITHUB_PATH"
 
     - name: Verify openclaw on PATH
       id: verify
       shell: bash
+      env:
+        ACTION_DIR: ${{ github.action_path }}
       run: |
         set -e
-        export PATH="$HOME/.npm-openclaw-global/bin:$PATH"
+        export PATH="$ACTION_DIR/node_modules/.bin:$PATH"
         which openclaw
         ver=$(openclaw --version 2>&1 | head -1)
         echo "openclaw version: $ver"