ci: poll for package availability after publish before triggering registry update (#1121)

.github/workflows/publish.yml

@@ -67,6 +67,8 @@ jobs:
     permissions:
       contents: read
       id-token: write
+    outputs:
+      version: ${{ steps.publish.outputs.version }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
         with:
@@ -78,7 +80,12 @@ jobs:
           registry-url: "https://registry.npmjs.org"
       - run: npm ci
       - run: npm run build
-      - run: npm publish
+      - name: Publish
+        id: publish
+        run: |
+          version="$(node -p "require('./package.json').version")"
+          npm publish
+          echo "version=$version" >> "$GITHUB_OUTPUT"
 
   # Same shape as publish-npm. Tagging is a separate job, so nothing here needs
   # write access to the repository.
@@ -207,7 +214,45 @@ jobs:
     runs-on: ubuntu-latest
     environment: release
     permissions: {}
+    # npm metadata is normally visible within about five minutes. Leave 2.5x that
+    # window for propagation, plus enough time to mint the token and dispatch.
+    timeout-minutes: 15
     steps:
+      - name: Wait for package to become available
+        if: ${{ needs.publish-npm.result == 'success' || needs.publish-npm-preview.outputs.published == 'true' }}
+        env:
+          PACKAGE: "@agentclientprotocol/claude-agent-acp"
+          VERSION: ${{ needs.publish-npm-preview.outputs.version || needs.publish-npm.outputs.version }}
+        #language=bash
+        run: |
+          if [ -z "$VERSION" ]; then
+            echo "::error::The publish job did not report a package version."
+            exit 1
+          fi
+
+          deadline=$((SECONDS + 750))
+          while (( SECONDS < deadline )); do
+            if timeout 10s npm pack "$PACKAGE@$VERSION" \
+              --dry-run \
+              --ignore-scripts \
+              --silent \
+              --registry=https://registry.npmjs.org \
+              --prefer-online \
+              --fetch-retries=0 >/dev/null 2>&1; then
+              echo "$PACKAGE@$VERSION is available from npm."
+              exit 0
+            fi
+
+            remaining=$((deadline - SECONDS))
+            if (( remaining > 0 )); then
+              echo "Waiting for $PACKAGE@$VERSION to become available (${remaining}s remaining)..."
+              sleep 10
+            fi
+          done
+
+          echo "::error::$PACKAGE@$VERSION was not available from npm after 12.5 minutes."
+          exit 1
+
       - name: Generate token scoped to the registry repo
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1
         id: registry-token

docs/RELEASES.md

@@ -55,14 +55,18 @@ handling for preview versions.
 
 Those are three jobs, in that order: `publish-npm-preview` mirrors `publish-npm`
 and does nothing but publish; `publish-tag-preview` creates the tag; and
-`trigger-registry-update` is shared with the stable path. The tag is a separate
-job so that a tag failure can be retried on its own with **Re-run failed jobs**
-— re-running the publish is not an option, because npm versions are immutable and
-publishing the same one twice fails outright.
+`trigger-registry-update` is shared with the stable path. Before dispatching,
+the registry job polls npm for the exact published version for up to 12.5 minutes,
+including downloading its tarball, so the registry never checks while npm is
+still propagating the package. The tag is a separate job so that a tag failure
+can be retried on its own with **Re-run failed jobs** — re-running the publish is
+not an option, because npm versions are immutable and publishing the same one
+twice fails outright.
 
 Both downstream jobs are gated on a `published` output that the publish step
-sets only after `npm publish --tag preview` succeeds. This ensures tagging and
-the registry update run only after the version has been published to npm.
+sets only after `npm publish --tag preview` succeeds. This ensures tagging runs
+only after publication and the registry update runs only after that exact version
+can also be downloaded from npm.
 
 A stable and a preview dispatch can never collide — a release merge publishes
 stable and skips the preview, every other push does the reverse — so the registry