fix(tools): attribute read-back to acting identity and paginate fully (#865)

Round 2 remediation for the read-back verification in issue-comment.sh and
pr-review.sh.

BLOCKER A (invocation attribution): id-above-boundary + content/state match
only proves temporal ordering — a concurrent write from a different identity
could satisfy it while this tea invocation created nothing. Both wrappers now
resolve the acting identity once via curl GET /api/v1/user and additionally
require the accepted record's author login to equal that identity. Residual
same-identity same-body/state concurrency is documented in-code (tea 0.11.1
emits no reliable created-record id to close it further).

BLOCKER B (pagination): the comments and reviews list reads now walk every
page (?limit=&page=1,2,… until a short/empty page) for both the pre-write
boundary and the post-write read-back, so a record beyond page 1 is still
found.

Adds regressions: concurrent different-identity write fails closed (comments
and reviews); a matching review beyond page 1 is still found. README updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/mosaic/framework/tools/git/pr-review.sh

@@ -193,8 +193,9 @@ PY
 }
 
 # Resolve and cache the Gitea REST endpoint + token for the current remote.
-# Populates GITEA_API_BASE and GITEA_API_TOKEN. Returns non-zero (with a
-# clear stderr message) on any resolution failure.
+# Populates GITEA_API_ROOT (…/api/v1), GITEA_API_BASE (…/api/v1/repos/<slug>),
+# and GITEA_API_TOKEN. Returns non-zero (with a clear stderr message) on any
+# resolution failure.
 gitea_resolve_api() {
     local host configured_url repo
 
@@ -211,31 +212,85 @@ gitea_resolve_api() {
         echo "Error: Could not resolve Gitea owner/repository relative to configured URL" >&2
         return 1
     }
-    GITEA_API_BASE="${configured_url%/}/api/v1/repos/$repo"
+    GITEA_API_ROOT="${configured_url%/}/api/v1"
+    GITEA_API_BASE="$GITEA_API_ROOT/repos/$repo"
     return 0
 }
 
-# Print the maximum existing review id on a PR (0 if none). This is the
-# pre-write BOUNDARY: Gitea pull-review ids are monotonic, so any review
-# submitted by a subsequent `tea pr approve`/`reject` has an id strictly
-# greater than this value. Bounding the read-back this way is what turns the
-# check into a genuine write-verification rather than a match against any
-# historical review — the same never-trust-exit-zero discipline #865 requires
-# for comments, applied to the review STATE itself.
-gitea_max_review_id() {
-    local pr_number="$1" response_file status
+# Fetch every page of a Gitea list endpoint into $2 (merged into one JSON
+# array). Gitea paginates list responses, so a single-page read would
+# false-negative once a newly created review/comment lands beyond page 1.
+# Walks page=1,2,… until a short or empty page is returned so the merged array
+# is exhaustive. $1 is the endpoint URL with NO query string. Returns non-zero
+# (clear stderr) on any transport / HTTP / parse failure.
+gitea_fetch_all() {
+    local base_url="$1" dest="$2" page=1 limit=50 status page_file count
 
-    response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-boundary.XXXXXX")
+    printf '[]' > "$dest"
+    while :; do
+        page_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-page.XXXXXX")
+        if ! status=$(curl -sS -o "$page_file" -w '%{http_code}' \
+            -H "Authorization: token $GITEA_API_TOKEN" \
+            "${base_url}?limit=${limit}&page=${page}"); then
+            rm -f "$page_file"
+            echo "Error: Gitea list read transport failed" >&2
+            return 1
+        fi
+        if [[ "$status" != "200" ]]; then
+            rm -f "$page_file"
+            echo "Error: Gitea list read failed with HTTP $status" >&2
+            return 1
+        fi
+        count=$(DEST="$dest" python3 - "$page_file" <<'PY'
+import json
+import os
+import sys
+
+try:
+    with open(os.environ["DEST"], encoding="utf-8") as merged_file:
+        merged = json.load(merged_file)
+    with open(sys.argv[1], encoding="utf-8") as page_file:
+        page = json.load(page_file)
+    if not isinstance(page, list):
+        raise ValueError("page response is not a list")
+    merged.extend(item for item in page if isinstance(item, dict))
+    with open(os.environ["DEST"], "w", encoding="utf-8") as merged_file:
+        json.dump(merged, merged_file)
+except (OSError, json.JSONDecodeError, TypeError, ValueError) as error:
+    print(f"Error: could not merge Gitea list page: {error}", file=sys.stderr)
+    raise SystemExit(1)
+print(len(page))
+PY
+) || { rm -f "$page_file"; return 1; }
+        rm -f "$page_file"
+        [[ "$count" -lt "$limit" ]] && break
+        page=$((page + 1))
+        if [[ "$page" -gt 1000 ]]; then
+            echo "Error: Gitea list pagination exceeded 1000 pages" >&2
+            return 1
+        fi
+    done
+    return 0
+}
+
+# Resolve the login of the identity the API token authenticates as (GET
+# /user). Used to attribute a read-back review to THIS action's reviewer so a
+# concurrent review from a DIFFERENT identity cannot satisfy verification.
+# Prints the login on success.
+gitea_authenticated_login() {
+    local response_file status
+
+    response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-whoami.XXXXXX")
     trap 'rm -f "$response_file"' RETURN
 
     if ! status=$(curl -sS -o "$response_file" -w '%{http_code}' \
         -H "Authorization: token $GITEA_API_TOKEN" \
-        "$GITEA_API_BASE/pulls/$pr_number/reviews"); then
-        echo "Error: Gitea review boundary read transport failed" >&2
+        "$GITEA_API_ROOT/user"); then
+        echo "Error: Gitea authenticated-identity read transport failed" >&2
         return 1
     fi
     if [[ "$status" != "200" ]]; then
-        echo "Error: Gitea review boundary read failed with HTTP $status" >&2
+        echo "Error: Gitea authenticated-identity read failed with HTTP $status" >&2
         return 1
     fi
 
@@ -243,11 +298,39 @@ gitea_max_review_id() {
 import json
 import sys
 
+try:
+    with open(sys.argv[1], encoding="utf-8") as response:
+        user = json.load(response)
+    login = user.get("login") if isinstance(user, dict) else None
+    if not isinstance(login, str) or not login:
+        raise ValueError("missing authenticated login")
+except (OSError, json.JSONDecodeError, TypeError, ValueError) as error:
+    print(f"Error: could not resolve authenticated Gitea identity: {error}", file=sys.stderr)
+    raise SystemExit(1)
+print(login)
+PY
+}
+
+# Print the maximum existing review id on a PR (0 if none). This is the
+# pre-write BOUNDARY: Gitea pull-review ids are monotonic, so any review
+# submitted by a subsequent `tea pr approve`/`reject` has an id strictly
+# greater than this value. Paginates fully so a boundary review beyond page 1
+# is still counted.
+gitea_max_review_id() {
+    local pr_number="$1" merged_file
+
+    merged_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-boundary.XXXXXX")
+    trap 'rm -f "$merged_file"' RETURN
+
+    gitea_fetch_all "$GITEA_API_BASE/pulls/$pr_number/reviews" "$merged_file" || return 1
+
+    python3 - "$merged_file" <<'PY'
+import json
+import sys
+
 try:
     with open(sys.argv[1], encoding="utf-8") as response:
         reviews = json.load(response)
-    if not isinstance(reviews, list):
-        raise ValueError("response is not a review list")
     ids = [r.get("id") for r in reviews if isinstance(r, dict) and isinstance(r.get("id"), int)]
     print(max(ids) if ids else 0)
 except (OSError, json.JSONDecodeError, TypeError, ValueError) as error:
@@ -258,21 +341,32 @@ PY
 
 # Independently verify that `tea pr approve`/`reject` produced a durable review
 # record — never trust tea's exit code alone (#865, same defect class). Require
-# a review that was created by THIS action: its id must be strictly greater
-# than the pre-write boundary, its state must equal the expected state
-# (APPROVED / REQUEST_CHANGES), and it must have been submitted against the
-# PR's current head commit. Prints the matched review id on success; fails
-# closed (non-zero, clear stderr) if no such review is found.
+# a review attributable to THIS action: its id must be strictly greater than
+# the pre-write boundary, its author login must equal the acting identity, its
+# state must equal the expected state (APPROVED / REQUEST_CHANGES), and it must
+# have been submitted against the PR's current head commit. The reviews list is
+# paginated fully so a matching review beyond page 1 is still found. Prints the
+# matched review id on success; fails closed (non-zero, clear stderr) if no
+# such review is found.
+#
+# id-above-boundary alone is only temporal ordering; the author-login check is
+# what excludes a concurrent review submitted by a DIFFERENT identity.
+#
+# Residual (documented, not eliminable without a tea-emitted created-record id,
+# which tea 0.11.1 does not reliably provide for approve/reject): a concurrent
+# review by the SAME identity with the same state against the same head inside
+# the boundary window could still be accepted. That is strictly narrower than
+# temporal-only matching.
 #
 # Args: $1 = PR number, $2 = expected state (APPROVED|REQUEST_CHANGES),
-#       $3 = pre-write boundary review id.
+#       $3 = pre-write boundary review id, $4 = acting reviewer login.
 gitea_verify_review_submitted() {
-    local pr_number="$1" expected_state="$2" boundary="$3"
-    local pr_response_file reviews_response_file status head_sha review_id
+    local pr_number="$1" expected_state="$2" boundary="$3" acting_login="$4"
+    local pr_response_file reviews_merged_file status head_sha review_id
 
     pr_response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-head.XXXXXX")
-    reviews_response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-state.XXXXXX")
-    trap 'rm -f "$pr_response_file" "$reviews_response_file"' RETURN
+    reviews_merged_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-state.XXXXXX")
+    trap 'rm -f "$pr_response_file" "$reviews_merged_file"' RETURN
 
     # Resolve the PR's current head commit so the review can be pinned to it.
     if ! status=$(curl -sS -o "$pr_response_file" -w '%{http_code}' \
@@ -302,19 +396,10 @@ print(head_sha)
 PY
 ) || return 1
 
-    if ! status=$(curl -sS -o "$reviews_response_file" -w '%{http_code}' \
-        -H "Authorization: token $GITEA_API_TOKEN" \
-        "$GITEA_API_BASE/pulls/$pr_number/reviews"); then
-        echo "Error: Gitea review read-back transport failed" >&2
-        return 1
-    fi
-    if [[ "$status" != "200" ]]; then
-        echo "Error: Gitea review read-back failed with HTTP $status" >&2
-        return 1
-    fi
+    gitea_fetch_all "$GITEA_API_BASE/pulls/$pr_number/reviews" "$reviews_merged_file" || return 1
 
-    review_id=$(EXPECTED_STATE="$expected_state" BOUNDARY_REVIEW_ID="$boundary" EXPECTED_HEAD_SHA="$head_sha" \
-        python3 - "$reviews_response_file" <<'PY'
+    review_id=$(EXPECTED_STATE="$expected_state" BOUNDARY_REVIEW_ID="$boundary" EXPECTED_HEAD_SHA="$head_sha" ACTING_LOGIN="$acting_login" \
+        python3 - "$reviews_merged_file" <<'PY'
 import json
 import os
 import sys
@@ -327,22 +412,24 @@ try:
     expected_state = os.environ["EXPECTED_STATE"]
     boundary = int(os.environ["BOUNDARY_REVIEW_ID"])
     expected_head = os.environ["EXPECTED_HEAD_SHA"]
-    # Require all of: created-after-boundary (this action's write), the
-    # expected review state, and pinned to the PR's current head commit.
-    # The monotonic id boundary is what proves "submitted by this action"
-    # rather than matching some pre-existing historical review.
+    acting_login = os.environ["ACTING_LOGIN"]
+    # Attribution to THIS action: created-after-boundary AND submitted by the
+    # acting reviewer identity AND expected state AND pinned to the PR's
+    # current head commit. The author check excludes a concurrent
+    # DIFFERENT-identity review that id+state+head alone would admit.
     matches = [
         r for r in reviews
         if isinstance(r, dict)
         and isinstance(r.get("id"), int)
         and r.get("id") > boundary
+        and (r.get("user") or {}).get("login") == acting_login
         and r.get("state") == expected_state
         and r.get("commit_id") == expected_head
     ]
     if not matches:
         raise ValueError(
-            f"no {expected_state} review created by this action found "
-            "(id > boundary, expected state, current head); "
+            f"no {expected_state} review attributable to this action found "
+            "(id > boundary, acting identity, expected state, current head); "
             "tea may have silently failed (#865 defect class)"
         )
     review_id = max(r["id"] for r in matches)
@@ -395,6 +482,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             # strictly-newer review created by THIS action (never trust tea's
             # exit code alone — #865 defect class applies to the review state).
             gitea_resolve_api || exit 1
+            ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             review_boundary=$(gitea_max_review_id "$PR_NUMBER") || exit 1
             # tea v0.11.1 defines no --comment/-comment flag on `pr approve`;
             # route any review body via the durable comment API instead (#835).
@@ -406,7 +494,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 TEA_ARGS+=(--login "$LOGIN_OVERRIDE")
             fi
             tea "${TEA_ARGS[@]}"
-            review_id=$(gitea_verify_review_submitted "$PR_NUMBER" "APPROVED" "$review_boundary") || {
+            review_id=$(gitea_verify_review_submitted "$PR_NUMBER" "APPROVED" "$review_boundary" "$ACTING_LOGIN") || {
                 echo "Error: could not verify an APPROVED review landed on Gitea PR #$PR_NUMBER via bounded read-back; treating tea's exit code as untrustworthy (#865)." >&2
                 exit 1
             }
@@ -427,6 +515,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             # Record the pre-write review-id boundary BEFORE the write (see the
             # approve path above for the rationale).
             gitea_resolve_api || exit 1
+            ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
             review_boundary=$(gitea_max_review_id "$PR_NUMBER") || exit 1
             # tea v0.11.1 defines no --comment/-comment flag on `pr reject`;
             # route the review body via the durable comment API instead (#835).
@@ -438,7 +527,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 TEA_ARGS+=(--login "$LOGIN_OVERRIDE")
             fi
             tea "${TEA_ARGS[@]}"
-            review_id=$(gitea_verify_review_submitted "$PR_NUMBER" "REQUEST_CHANGES" "$review_boundary") || {
+            review_id=$(gitea_verify_review_submitted "$PR_NUMBER" "REQUEST_CHANGES" "$review_boundary" "$ACTING_LOGIN") || {
                 echo "Error: could not verify a REQUEST_CHANGES review landed on Gitea PR #$PR_NUMBER via bounded read-back; treating tea's exit code as untrustworthy (#865)." >&2
                 exit 1
             }