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/issue-comment.sh

@@ -73,8 +73,9 @@ fi
 detect_platform >/dev/null
 
 # 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) if any part of the resolution fails.
+# 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) if any
+# part of the resolution fails.
 gitea_resolve_api() {
     local host configured_url repo
 
@@ -91,31 +92,86 @@ 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 comment id on an issue (0 if none). This is the
-# pre-write BOUNDARY: Gitea comment ids are monotonic, so any comment created
-# by a subsequent write has an id strictly greater than this value. Bounding
-# the read-back this way is what distinguishes a genuine fresh write from a
-# pre-existing comment that merely happens to share the same body — the exact
-# false-positive a body-only, whole-history match would miss when `tea
-# comment` silently no-ops (#865).
-gitea_max_comment_id() {
-    local issue_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 record lands beyond page 1. Walks
+# page=1,2,… until a short page (fewer than the requested limit) or an 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-issue-comment-boundary.XXXXXX")
+    printf '[]' > "$dest"
+    while :; do
+        page_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-issue-comment-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 record to THIS invocation's writer so
+# a concurrent write 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-issue-comment-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/issues/$issue_number/comments"); then
-        echo "Error: Gitea comment 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 comment boundary read failed with HTTP $status" >&2
+        echo "Error: Gitea authenticated-identity read failed with HTTP $status" >&2
         return 1
     fi
 
@@ -123,11 +179,37 @@ gitea_max_comment_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 comment id on an issue (0 if none). This is the
+# pre-write BOUNDARY: Gitea comment ids are monotonic, so any comment created
+# by a subsequent write has an id strictly greater than this value.
+gitea_max_comment_id() {
+    local issue_number="$1" merged_file
+
+    merged_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-issue-comment-boundary.XXXXXX")
+    trap 'rm -f "$merged_file"' RETURN
+
+    gitea_fetch_all "$GITEA_API_BASE/issues/$issue_number/comments" "$merged_file" || return 1
+
+    python3 - "$merged_file" <<'PY'
+import json
+import sys
+
 try:
     with open(sys.argv[1], encoding="utf-8") as response:
         comments = json.load(response)
-    if not isinstance(comments, list):
-        raise ValueError("response is not a comment list")
     ids = [c.get("id") for c in comments if isinstance(c, dict) and isinstance(c.get("id"), int)]
     print(max(ids) if ids else 0)
 except (OSError, json.JSONDecodeError, TypeError, ValueError) as error:
@@ -136,31 +218,29 @@ except (OSError, json.JSONDecodeError, TypeError, ValueError) as error:
 PY
 }
 
-# Independently re-fetch the issue's comments via the Gitea REST API and
-# require a comment that was created by THIS write: its id must be strictly
-# greater than the pre-write boundary AND its body must exactly match what we
-# submitted (see header comment: tea's exit code is not trustworthy evidence
-# of a durable write on its own). Prints the matched comment ID on success.
+# Independently re-fetch (all pages of) the issue's comments and require a
+# comment attributable to THIS invocation: id strictly greater than the
+# pre-write boundary AND author login equal to the acting identity AND exact
+# body match. tea's exit code is not trustworthy evidence of a durable write
+# on its own (#865); id-above-boundary alone is only temporal ordering, so the
+# author-login check is what excludes a concurrent write by a DIFFERENT
+# identity. Prints the matched comment ID on success.
+#
+# Residual (documented, not eliminable without a tea-emitted created-record
+# id, which tea 0.11.1 does not reliably provide): a concurrent write by the
+# SAME identity with an identical body inside the boundary window could still
+# be accepted. That is a strictly narrower window than temporal-only matching.
 gitea_verify_comment_posted() {
-    local issue_number="$1" comment_body="$2" boundary="$3"
-    local readback_response_file status
+    local issue_number="$1" comment_body="$2" boundary="$3" acting_login="$4"
+    local merged_file
 
-    readback_response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-issue-comment-readback.XXXXXX")
-    trap 'rm -f "$readback_response_file"' RETURN
+    merged_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-issue-comment-readback.XXXXXX")
+    trap 'rm -f "$merged_file"' RETURN
 
-    if ! status=$(curl -sS -o "$readback_response_file" -w '%{http_code}' \
-        -H "Authorization: token $GITEA_API_TOKEN" \
-        "$GITEA_API_BASE/issues/$issue_number/comments"); then
-        echo "Error: Gitea comment read-back transport failed" >&2
-        return 1
-    fi
-    if [[ "$status" != "200" ]]; then
-        echo "Error: Gitea comment read-back failed with HTTP $status" >&2
-        return 1
-    fi
+    gitea_fetch_all "$GITEA_API_BASE/issues/$issue_number/comments" "$merged_file" || return 1
 
-    EXPECTED_COMMENT_BODY="$comment_body" BOUNDARY_COMMENT_ID="$boundary" \
-        python3 - "$readback_response_file" <<'PY'
+    EXPECTED_COMMENT_BODY="$comment_body" BOUNDARY_COMMENT_ID="$boundary" ACTING_LOGIN="$acting_login" \
+        python3 - "$merged_file" <<'PY'
 import json
 import os
 import sys
@@ -172,17 +252,22 @@ try:
         raise ValueError("response is not a comment list")
     expected_body = os.environ["EXPECTED_COMMENT_BODY"]
     boundary = int(os.environ["BOUNDARY_COMMENT_ID"])
-    # Require both: created-after-boundary (fresh write) AND exact body match.
+    acting_login = os.environ["ACTING_LOGIN"]
+    # Attribution to THIS write: created-after-boundary AND authored by the
+    # acting identity AND exact body match. The author check excludes a
+    # concurrent DIFFERENT-identity writer that id+body alone would admit.
     matches = [
         c for c in comments
         if isinstance(c, dict)
         and isinstance(c.get("id"), int)
         and c.get("id") > boundary
+        and (c.get("user") or {}).get("login") == acting_login
         and c.get("body") == expected_body
     ]
     if not matches:
         raise ValueError(
-            "no comment created by this write matched (id > boundary and exact body); "
+            "no comment attributable to this write matched "
+            "(id > boundary, acting identity, exact body); "
             "tea may have silently no-opped (#865)"
         )
     comment_id = max(c["id"] for c in matches)
@@ -206,9 +291,11 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
         exit 1
     }
 
-    # Resolve the REST endpoint and record the pre-write boundary BEFORE the
-    # write, so the read-back can require a strictly-newer comment id.
+    # Resolve the REST endpoint, the acting identity, and the pre-write
+    # boundary BEFORE the write, so the read-back can require a strictly-newer
+    # comment id authored by this identity.
     gitea_resolve_api || exit 1
+    ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
     boundary=$(gitea_max_comment_id "$ISSUE_NUMBER") || exit 1
 
     TEA_ARGS=(comment "$ISSUE_NUMBER" "$COMMENT" --repo "$REPO_SLUG" --login "$GITEA_LOGIN_NAME")
@@ -220,7 +307,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
     fi
     tea "${TEA_ARGS[@]}"
 
-    comment_id=$(gitea_verify_comment_posted "$ISSUE_NUMBER" "$COMMENT" "$boundary") || {
+    comment_id=$(gitea_verify_comment_posted "$ISSUE_NUMBER" "$COMMENT" "$boundary" "$ACTING_LOGIN") || {
         echo "Error: could not verify comment landed on Gitea issue #$ISSUE_NUMBER via bounded read-back; treating tea's exit code as untrustworthy (#865)." >&2
         exit 1
     }