fix(release): pin the audited SHA through dispatch and workflow

Closes a mutable-ref race in the release path: the origin-moved guard
read the local remote-tracking ref (minutes stale) and release.yml
resolved a mutable branch at dispatch. The helper now re-reads the
live remote head via git ls-remote immediately before dispatch and
passes expected-sha; the workflow refuses to publish when GITHUB_SHA
differs. Manual dispatches without expected-sha warn instead.

Found in pre-release audit (Schrodinger).

Author: lidge-jun

.github/workflows/release.yml

@@ -24,6 +24,10 @@ on:
         required: false
         type: boolean
         default: true
+      expected-sha:
+        description: "Immutable release commit this dispatch must publish (fail if the branch moved)"
+        required: false
+        type: string
 
 permissions:
   contents: write # create the matching GitHub Release + version tag after npm publish
@@ -44,6 +48,17 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Verify dispatched SHA
+        env:
+          EXPECTED_SHA: ${{ inputs.expected-sha }}
+        run: |
+          if [ -z "$EXPECTED_SHA" ]; then
+            echo "::warning::no expected-sha supplied; publishing whatever the branch currently points at"
+          elif [ "$GITHUB_SHA" != "$EXPECTED_SHA" ]; then
+            echo "::error::branch moved after the release audit (expected ${EXPECTED_SHA}, got ${GITHUB_SHA}) — refusing to publish an unaudited commit"
+            exit 1
+          fi
+
       # opencodex is bun-native (the prepublishOnly GUI build + typecheck run under bun).
       - name: Setup Bun
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2

scripts/release.ts

@@ -201,6 +201,17 @@ async function _remoteMainSha(): Promise<string> {
   return sha;
 }
 
+/** Live (network) head of a remote branch — never the local remote-tracking ref. */
+async function remoteBranchHead(branch: string): Promise<string> {
+  const out = (await $`git ls-remote origin refs/heads/${branch}`.text()).trim();
+  const [sha] = out.split(/\s+/);
+  if (!sha) {
+    console.error(`✗ could not resolve origin/${branch}`);
+    process.exit(1);
+  }
+  return sha;
+}
+
 if (args[0] === "watch") {
   await watchLatest();
   process.exit(0);
@@ -263,15 +274,19 @@ await waitForSuccessfulCi(releaseSha);
 console.log(`→ wait for Service lifecycle (${releaseSha})`);
 await waitForSuccessfulCi(releaseSha, SERVICE_WORKFLOW, "Service lifecycle");
 
-const originSha = (await $`git rev-parse origin/${branch}`.text()).trim();
-if (originSha !== releaseSha) {
-  console.error(`✗ origin/${branch} moved while waiting for CI (${originSha} != ${releaseSha}); aborting release dispatch.`);
+// Live-remote guard: re-read the actual remote head over the network immediately
+// before dispatch. The local remote-tracking ref can be minutes stale, and the
+// workflow_dispatch below resolves a mutable branch — so this is the last chance
+// to refuse publishing an unaudited newer commit.
+const liveOriginSha = await remoteBranchHead(branch);
+if (liveOriginSha !== releaseSha) {
+  console.error(`✗ origin/${branch} moved while waiting for CI (${liveOriginSha} != ${releaseSha}); aborting release dispatch.`);
   process.exit(1);
 }
 
 console.log(`→ dispatch Release (tag=${tag}, dry-run=${dryRun})`);
 const dispatchStartedAt = new Date(Date.now() - 5_000).toISOString();
-await $`gh workflow run release.yml --ref ${branch} -f version=${version} -f tag=${tag} -f dry-run=${String(dryRun)}`;
+await $`gh workflow run release.yml --ref ${branch} -f version=${version} -f tag=${tag} -f expected-sha=${releaseSha} -f dry-run=${String(dryRun)}`;
 
 // 5. Watch it.
 const releaseRun = await waitForReleaseWorkflowRun(releaseSha, branch, dispatchStartedAt);

tests/release-helper.test.ts

@@ -18,6 +18,7 @@ interface LoggedCall {
 interface ReleaseScenario {
   branch?: string;
   headSha?: string;
+  remoteHeadSha?: string;
   privacyExitCode?: number;
   testExitCode?: number;
   typecheckExitCode?: number;
@@ -71,6 +72,10 @@ if (args[0] === "status" && args[1] === "--porcelain") {
 }
 
 if (args[0] === "ls-remote") {
+  if (args.some(a => typeof a === "string" && a.startsWith("refs/heads/"))) {
+    const branchRef = args.find(a => typeof a === "string" && a.startsWith("refs/heads/"));
+    stdout(\`\${process.env.FAKE_GIT_REMOTE_HEAD_SHA ?? headSha}\t\${branchRef}\n\`);
+  }
   process.exit(0);
 }
 
@@ -194,6 +199,7 @@ function runRelease(version: string, scenario: ReleaseScenario = {}) {
       FAKE_RELEASE_LOG: logPath,
       FAKE_GIT_BRANCH: scenario.branch ?? "main",
       FAKE_GIT_HEAD_SHA: scenario.headSha ?? "abc123def456",
+      ...(scenario.remoteHeadSha ? { FAKE_GIT_REMOTE_HEAD_SHA: scenario.remoteHeadSha } : {}),
       FAKE_BUN_TSC_EXIT_CODE: String(scenario.typecheckExitCode ?? 0),
       FAKE_BUN_TEST_EXIT_CODE: String(scenario.testExitCode ?? 0),
       FAKE_BUN_PRIVACY_EXIT_CODE: String(scenario.privacyExitCode ?? 0),
@@ -253,4 +259,27 @@ describe("release helper", () => {
       && call.args.includes("dry-run=true"),
     )).toBeGreaterThanOrEqual(0);
   });
+
+  test("dispatch pins the audited release SHA via expected-sha", () => {
+    const { calls, result } = runRelease("9.9.9", { headSha: "deadbeefcafe1234" });
+
+    expect(result.status).toBe(0);
+    expect(findCallIndex(calls, "gh", call =>
+      call.args[0] === "workflow"
+      && call.args[1] === "run"
+      && call.args.includes("release.yml")
+      && call.args.includes("expected-sha=deadbeefcafe1234"),
+    )).toBeGreaterThanOrEqual(0);
+  });
+
+  test("aborts before dispatch when the remote branch moved during the CI wait", () => {
+    const { calls, result } = runRelease("9.9.9", {
+      headSha: "abc123def456",
+      remoteHeadSha: "9999999999999999999999999999999999999999",
+    });
+
+    expect(result.status).not.toBe(0);
+    expect(result.stderr + result.stdout).toContain("moved while waiting for CI");
+    expect(findCallIndex(calls, "gh", call => call.args[0] === "workflow" && call.args[1] === "run")).toBe(-1);
+  });
 });