From adcf5bd93adf50a10b28d91f47d0fc7d37b75316 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 9 Aug 2026 00:15:08 -0700
Subject: [PATCH] ci: acknowledge pull request receipts in clawsweeper dispatch
 (#120934)

Propagate the receipt-acknowledgment steps from the canonical
ClawSweeper dispatch template (openclaw/clawsweeper#1080): mint a
minimal issues:write App token and post an idempotent
clawsweeper-pr-ack marker comment for non-draft opened and
ready_for_review pull requests, before review dispatch.
---
 .github/workflows/clawsweeper-dispatch.yml | 64 ++++++++++++++++++++++
 docs/reference/pull-request-review-flow.md |  4 +-
 2 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/clawsweeper-dispatch.yml b/.github/workflows/clawsweeper-dispatch.yml
index 68c8676b196c..67b897a18c48 100644
--- a/.github/workflows/clawsweeper-dispatch.yml
+++ b/.github/workflows/clawsweeper-dispatch.yml
@@ -118,6 +118,70 @@ jobs:
           permission-issues: write
           permission-pull-requests: read
 
+      - name: Create target PR acknowledgement token
+        id: pr_ack_token
+        if: >-
+          ${{
+            github.event_name == 'pull_request_target' &&
+            (
+              github.event.action == 'ready_for_review' ||
+              (github.event.action == 'opened' && github.event.pull_request.draft == false)
+            ) &&
+            env.HAS_CLAWSWEEPER_APP_PRIVATE_KEY == 'true'
+          }}
+        continue-on-error: true
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ env.CLAWSWEEPER_APP_CLIENT_ID }}
+          private-key: ${{ secrets.CLAWSWEEPER_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: ${{ github.event.repository.name }}
+          permission-issues: write
+
+      - name: Acknowledge received pull request
+        if: >-
+          ${{
+            github.event_name == 'pull_request_target' &&
+            (
+              github.event.action == 'ready_for_review' ||
+              (github.event.action == 'opened' && github.event.pull_request.draft == false)
+            ) &&
+            env.HAS_CLAWSWEEPER_APP_PRIVATE_KEY == 'true'
+          }}
+        continue-on-error: true
+        env:
+          ACK_TOKEN: ${{ steps.pr_ack_token.outputs.token }}
+          TARGET_REPO: ${{ github.repository }}
+          ITEM_NUMBER: ${{ github.event.pull_request.number }}
+          SOURCE_ACTION: ${{ github.event.action }}
+        run: |
+          set -euo pipefail
+          if [ -z "$ACK_TOKEN" ]; then
+            echo "::notice::Skipping ClawSweeper pull request acknowledgement because no target credential is configured."
+            exit 0
+          fi
+          comments="$(GH_TOKEN="$ACK_TOKEN" gh api \
+            "repos/$TARGET_REPO/issues/$ITEM_NUMBER/comments?per_page=100")"
+          if jq -e \
+            --arg marker_prefix "clawsweeper-pr-ack:" \
+            --arg marker_suffix " item=$ITEM_NUMBER -->" \
+            'any(.[]; (.body // "") as $body | ($body | contains($marker_prefix)) and ($body | contains($marker_suffix)))' \
+            <<< "$comments" >/dev/null; then
+            echo "ClawSweeper pull request acknowledgement already exists."
+            exit 0
+          fi
+          ack_body="$(printf '%s\n' \
+            "<!-- clawsweeper-pr-ack:$SOURCE_ACTION item=$ITEM_NUMBER -->" \
+            "🦞👀" \
+            "ClawSweeper picked this up." \
+            "" \
+            "Pull request received. I will update this pull request when review starts.")"
+          ack_payload="$(jq -nc --arg body "$ack_body" '{body:$body}')"
+          GH_TOKEN="$ACK_TOKEN" gh api \
+            "repos/$TARGET_REPO/issues/$ITEM_NUMBER/comments" \
+            --method POST \
+            --input - <<< "$ack_payload"
+
       - name: Dispatch GitHub activity to ClawSweeper
         env:
           GH_TOKEN: ${{ steps.token.outputs.token }}
diff --git a/docs/reference/pull-request-review-flow.md b/docs/reference/pull-request-review-flow.md
index 06332384aa5e..83ebe3a2e49a 100644
--- a/docs/reference/pull-request-review-flow.md
+++ b/docs/reference/pull-request-review-flow.md
@@ -45,7 +45,9 @@ and help maintainers with guarded repair or automerge flows.
 A positive ClawSweeper result is supporting evidence, not maintainer approval.
 Maintainers still decide whether and when a PR is ready to merge.
 
-ClawSweeper is queue-based. Do not expect an immediate response after opening a
+ClawSweeper is queue-based. When you open a non-draft PR or mark a draft ready
+for review, it posts a short receipt comment right away, but the review itself
+still waits for a queue slot. Do not expect an immediate review after opening a
 PR, pushing a commit, or adding a review request. Label updates after a
 ClawSweeper run can also take time.