1.9.0: stage the browser sidecar's npm releases, and fail a release whose sidecar changed under a published version

.github/scripts/browser-sidecar-unchanged.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Fails when browser-sidecar/ packs differently from the version of
+# @activeagents/browser-sidecar already on npm: a published version is never
+# published again, so a sidecar change needs a new version.
+#
+#   .github/scripts/browser-sidecar-unchanged.sh browser-sidecar 1.9.0
+set -euo pipefail
+
+dir="$(cd "${1:?the sidecar directory}" && pwd)"
+version="${2:?the version on npm}"
+package="@activeagents/browser-sidecar@${version}"
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+mkdir -p "$work/published" "$work/repo"
+
+# Both tarballs share a file name, so each is packed into its own directory.
+published="$(cd "$work/published" && npm pack "$package" --silent)"
+repo="$(cd "$dir" && npm pack --silent --pack-destination "$work/repo")"
+tar -xzf "$work/published/$published" -C "$work/published"
+tar -xzf "$work/repo/$repo" -C "$work/repo"
+
+if ! diff -r "$work/published/package" "$work/repo/package" > "$work/diff.txt"; then
+  echo "::error::browser-sidecar changed since ${package} was published; bump the version (browser-sidecar/package.json and ActionAgent::VERSION)."
+  head -n 80 "$work/diff.txt"
+  exit 1
+fi
+echo "browser-sidecar matches ${package} on npm."

.github/workflows/release.yml

@@ -13,9 +13,17 @@ name: Release
 # fails with an authorization error and the other gem is unaffected.
 #
 # The browser sidecar (browser-sidecar/) is published at the dashboard's
-# version too: the npm package with the NPM_TOKEN secret, and the image to
+# version too: the npm package through npm trusted publishing (OIDC, no
+# stored token) as a staged publish, and the image to
 # ghcr.io/activeagents/browser-sidecar with the workflow's own token. Each is
-# skipped when that version is already published.
+# skipped when that version is already published; the npm job then fails if
+# browser-sidecar/ no longer packs the same as that published version, since
+# a sidecar change needs a new version.
+#
+# A staged publish is not public until a maintainer approves it with 2FA, on
+# npmjs.com or with `npm stage approve` (`npm stage list` shows what waits).
+# The trusted publisher on npmjs.com for @activeagents/browser-sidecar must
+# name this repository and this workflow file (release.yml).
 on:
   push:
     tags: [ "v*" ]
@@ -112,19 +120,21 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      id-token: write # npm provenance
+      id-token: write # npm trusted publishing (OIDC); provenance comes with it
     defaults:
       run:
         working-directory: browser-sidecar
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           registry-url: https://registry.npmjs.org
-      - name: Publish the package unless this version is on npm
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      # Trusted publishing needs npm 11.5.1 or later, and `npm stage` a
+      # recent 11.x; the npm bundled with Node may be older.
+      - name: Update npm
+        run: npm install -g npm@11
+      - name: Stage the package unless this version is on npm
         run: |
           version="$(node -p 'require("./package.json").version')"
           engine="$(sed -nE 's/^ *VERSION = "([^"]+)".*/\1/p' ../actionagent/lib/action_agent/version.rb)"
@@ -133,11 +143,15 @@ jobs:
             exit 1
           fi
           if npm view "@activeagents/browser-sidecar@${version}" version > /dev/null 2>&1; then
+            # Skipping is right only when the sidecar is what was published:
+            # a change released under a published version would never reach npm.
+            ../.github/scripts/browser-sidecar-unchanged.sh . "$version"
             echo "@activeagents/browser-sidecar ${version} is already on npm; skipping."
             exit 0
           fi
           npm ci
-          npm publish --provenance --access public
+          npm stage publish
+          echo "::notice::@activeagents/browser-sidecar ${version} is staged; approve it on npmjs.com or with npm stage approve."
 
   publish-browser-sidecar-image:
     if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'