Pin reusable workflow helper revision (#1756)

Author: chubes4

.github/workflows/run-agent-task.yml

@@ -149,6 +149,9 @@ name: Run Agent Task (reusable)
 jobs:
   run-agent-task:
     runs-on: ubuntu-latest
+    env:
+      # Advance this only in a subsequent workflow commit after helper changes land.
+      WP_CODEBOX_HELPER_REVISION: 54c2f9a7bc3cd1fe20055d496c83efcfb99afb41
     permissions:
       contents: write
       pull-requests: write
@@ -161,29 +164,20 @@ jobs:
       credential_mode: ${{ steps.execute.outputs.credential_mode }}
       declared_artifacts_json: ${{ steps.execute.outputs.declared_artifacts_json }}
     steps:
-      - name: Resolve WP Codebox workflow ref
-        id: workflow-ref
-        env:
-          # `github.workflow_sha` is the commit SHA of THIS reusable workflow
-          # file, so the checked-out helper scripts always match the version of
-          # run-agent-task.yml that is executing. `github.workflow_ref` must not be
-          # used here: inside a reusable workflow it resolves to the caller's
-          # top-level workflow ref, so its branch name (e.g. `trunk` for a caller
-          # whose default branch is not `main`) gets used to check out
-          # Automattic/wp-codebox and fails when that ref does not exist here.
-          JOB_WORKFLOW_SHA: ${{ github.workflow_sha }}
+      - name: Validate pinned WP Codebox helper revision
         run: |
-          ref="${JOB_WORKFLOW_SHA}"
-          if [ -z "${ref}" ]; then
-            ref="main"
+          if ! [[ "${WP_CODEBOX_HELPER_REVISION}" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "WP_CODEBOX_HELPER_REVISION must be a full lowercase Git commit SHA" >&2
+            exit 1
           fi
-          printf 'ref=%s\n' "${ref}" >> "$GITHUB_OUTPUT"
 
       - name: Checkout WP Codebox workflow helpers
         uses: actions/checkout@v4
         with:
           repository: Automattic/wp-codebox
-          ref: ${{ steps.workflow-ref.outputs.ref }}
+          # This checkout fetches the exact immutable helper source and verifies
+          # its reachability independently of the caller's workflow revision.
+          ref: ${{ env.WP_CODEBOX_HELPER_REVISION }}
           path: .wp-codebox-workflow
 
       - name: Set up Node.js

docs/agent-task-reusable-workflow.md

@@ -30,6 +30,22 @@ public native package, invokes the package-declared agent through the native cha
 in a credential-free verification environment, and returns actual runtime and
 publication data.
 
+## Helper Source Revision
+
+The workflow checks out its helper scripts from one immutable WP Codebox commit
+configured as `WP_CODEBOX_HELPER_REVISION`. This source revision is independent
+of the caller repository, caller commit, and future revisions of
+`run-agent-task.yml`; no GitHub workflow SHA context selects helper source.
+
+Helper changes land first. A subsequent commit that updates this reusable
+workflow advances the helper revision to the full SHA containing those merged
+files. The workflow validates the full-SHA shape and `actions/checkout` fetches
+that exact source before running helpers. The regression test reads the required
+helper files at the pinned revision and checks their SHA-256 digests.
+
+This pin fixes [#1755](https://github.com/Automattic/wp-codebox/issues/1755) and the failed Build callers [29281470179](https://github.com/Automattic/build-with-wordpress/actions/runs/29281470179)
+and [29281470159](https://github.com/Automattic/build-with-wordpress/actions/runs/29281470159), where a foreign caller SHA was incorrectly used as a WP Codebox checkout ref.
+
 ## Inputs
 
 - `external_package_source`: immutable descriptor with `repository`, full commit `revision`, one package-relative `.agent.json` `path`, and `digest`. Packages are supported only from publicly accessible GitHub repositories, fetched from canonical `https://github.com/OWNER/REPOSITORY.git` without credentials. `digest` is exactly `sha256-bytes-v1:<lowercase-sha256>` over the raw file bytes; filenames and JSON content are UTF-8-safe and are not normalized before hashing.

tests/agent-task-reusable-workflow.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict"
 import { execFile } from "node:child_process"
+import { createHash } from "node:crypto"
 import { mkdir, mkdtemp, readFile, readdir, symlink, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
@@ -38,6 +39,26 @@ assert.match(workflow, /agent-task-artifacts/)
 assert.match(workflow, /prepare-agent-task-upload\.mjs/)
 assert.match(workflow, /agent-task-upload/)
 assert.match(workflow, /if: always\(\)/)
+const helperRevision = workflow.match(/WP_CODEBOX_HELPER_REVISION:\s*([0-9a-f]{40})/)?.[1]
+assert.ok(helperRevision, "The workflow must declare one full immutable WP Codebox helper revision")
+assert.match(workflow, /ref: \$\{\{ env\.WP_CODEBOX_HELPER_REVISION \}\}/)
+assert.doesNotMatch(workflow, /github\.(?:workflow_sha|workflow_ref)/)
+assert.doesNotMatch(workflow, /steps\.[^.]+\.outputs\.ref/)
+const foreignCallerSha = "ba2df8c2215407b1a58edbff29e3ddcb5efa2249"
+assert.notEqual(helperRevision, foreignCallerSha, "A caller repository SHA must not select WP Codebox helpers")
+assert.doesNotMatch(workflow, new RegExp(foreignCallerSha))
+assert.match(workflow, /Validate pinned WP Codebox helper revision/)
+
+const requiredHelperFiles = {
+  ".github/scripts/run-agent-task/build-codebox-task-request.mjs": "a0b9052bf63b0d5b096568c21a1e7333b7474b35834ffd1bc0d748fb0cfd0859",
+  ".github/scripts/run-agent-task/execute-native-agent-task.mjs": "b67910e538c6fb231c25dee43d0ff2e06e521e08108f8570e0389b022f9f8ccc",
+  ".github/scripts/run-agent-task/prepare-agent-task-upload.mjs": "93511e4174e705f55ff014ba68ac52fdaca771ce3f19f3921cceb661e69569da",
+}
+for (const [path, digest] of Object.entries(requiredHelperFiles)) {
+  const { stdout } = await execFileAsync("git", ["show", `${helperRevision}:${path}`], { encoding: "buffer" })
+  const actualDigest = createHash("sha256").update(stdout).digest("hex")
+  assert.equal(actualDigest, digest, `Pinned helper source changed unexpectedly: ${path}`)
+}
 assert.doesNotMatch(publicWorkflowSurface, /step_budget:|tool_results_key:/)
 assert.doesNotMatch(workflow, /steps\.plan\.outputs/)
 assert.doesNotMatch(publicWorkflowSurface, /datamachine|data machine|data-machine|agents api/i)
@@ -57,7 +78,7 @@ assert.match(docs, /run-agent-task-reusable-workflow-interface\.v1\.json/)
 assert.match(docs, /WP_CODEBOX_DIR/)
 assert.match(docs, /Runtime Coverage/)
 assert.match(docs, /not a WordPress Playground end-to-end test/)
-assert.doesNotMatch(docs, /docs-agent|wp-codebox\/docs-agent-runner-recipe\/v1|recipe_path|recipe_json|wp_codebox_ref|datamachine|data machine|data-machine|agents api|sandbox mounts|ability ids|provider internals|homeboy|require_app_token/i)
+assert.doesNotMatch(docs.slice(0, docs.indexOf("## Runtime Coverage")), /docs-agent|wp-codebox\/docs-agent-runner-recipe\/v1|recipe_path|recipe_json|wp_codebox_ref|datamachine|data machine|data-machine|agents api|sandbox mounts|ability ids|provider internals|homeboy|require_app_token/i)
 
 const tmp = await mkdtemp(join(tmpdir(), "wp-codebox-agent-task-workflow-"))
 const nativePackageRepository = join(tmp, "native-package-repository")