fix(tools): write Gitea reviews/comments via REST POST and verify by exact created id (#865)

Replace the tea-based write + boundary/author read-back with a direct Gitea
REST POST that returns the created record's id, and verify that exact record.

BLOCKER 2 (credential ordering): resolve the acting identity, the write token,
and the read-back token from the SAME effective login. A --login override now
selects the credential used for the POST, GET /user, and the GET-by-id
read-back, so an overridden write is verified against the identity that
performed it -- not the host default. Login-name resolution is best-effort and
non-fatal (the override always wins; otherwise fall back to the host
credential), so exotic/ported hosts still resolve a token.

BLOCKER 1+3 (attribution + tautological tests): the write is now
POST /issues/{n}/comments or POST /pulls/{n}/reviews (event + body + commit_id
== PR head), parsing the provider-returned created id. Verification GETs that
exact id and checks author == acting identity and body (comments) or state +
commit_id (reviews). Keying on the created id closes the concurrency window:
a no-op create yields no id and fails closed with no list-scan fallback, and a
concurrent same-identity record has a different id. The review body travels in
the review submit, removing the separate detached comment.

Tests: the curl stub now models a real server with persistent on-disk
review/comment state -- a POST actually creates+persists a record and returns
its id, and the read-back reads that same state (no fabricated record for the
wrapper to find). Adds same-identity no-op-concurrent and author-mismatch
fail-closed cases for both comments and reviews, and >page-1 pagination
coverage for both. README "Durable review provenance" refreshed for the REST
mechanism.

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

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

@@ -2,16 +2,20 @@
 # pr-review.sh - Review a pull request on GitHub or Gitea
 # Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>]
 #
-# --login override: approve/request-changes on Gitea invoke `tea pr
-# approve`/`tea pr reject` with a `--login` resolved from the local tea
-# login list for this repo's host (get_gitea_login_for_host). Pass
-# --login <name> to override that default for this invocation only. The
-# override is appended to the tea command line AFTER the detected default
-# (get_gitea_repo_args()-equivalent resolution happens first), because tea
-# honors only the LAST `--login` flag on its command line — a flag placed
-# before the default would be silently clobbered by it. The `comment`
-# action does not shell out to `tea` at all (see gitea_post_verified_comment
-# below), so --login has no effect on it.
+# Gitea reviews and comments are written through the supported REST API, not
+# `tea`: tea 0.11.1 cannot emit the id of a record it creates and can silently
+# no-op while exiting 0 (#865 defect class), so an exit code is the only — and
+# untrustworthy — signal it offers. approve/request-changes POST to
+# /pulls/{n}/reviews (returns the created review with its id); the `comment`
+# action POSTs to /issues/{n}/comments (returns the created comment with its
+# id). Each write is then verified by GETting that exact returned id, so a
+# concurrent record cannot masquerade as this write and a no-op fails closed.
+#
+# --login override: the default login is resolved from the local tea login list
+# for this repo's host (get_gitea_login_for_host). Pass --login <name> to
+# override it for this invocation only. The REST write, the /user identity read,
+# and every read-back are ALL performed with the token of the EFFECTIVE login,
+# so the write and its verification bind to the same identity.
 
 set -e
 
@@ -73,51 +77,37 @@ fi
 
 detect_platform >/dev/null
 
-# Post a review comment body to a Gitea PR via the supported comments REST API
-# and verify it durably via provider read-back (see docs on durable review
-# provenance in README.md). Used by the `comment` action and, since `tea`
-# v0.11.1 defines no `--comment`/`-comment` flag on `pr approve`/`pr reject`,
-# also by the `approve` and `request-changes` actions to carry an optional
-# review body that `tea` itself cannot attach.
+# Post a comment to a Gitea PR (PR comments ARE issue comments) via the
+# supported REST API and verify it against a PROVIDER-RETURNED created id. The
+# write is a direct POST that returns the created comment object, so we learn
+# the exact id of THIS write; we GET that exact id and require id == created id
+# AND author == acting identity AND exact body AND that it belongs to this PR.
+# Keying to the returned id means no concurrent comment (even same identity /
+# body) can masquerade as this write, and a no-op create yields no id and fails
+# closed. Requires GITEA_API_BASE / GITEA_API_TOKEN to be resolved first (via
+# gitea_resolve_api_for_login). Prints the created comment id on success.
 #
-# Args: $1 = PR number, $2 = comment body
-# On success: prints only the created comment ID to stdout, returns 0.
-# On failure: prints an error to stderr, returns 1.
-gitea_post_verified_comment() {
-    local pr_number="$1" comment_body="$2"
-    local host token configured_url repo api_base payload
-    local write_response_file readback_response_file comment_id
+# Args: $1 = PR number, $2 = comment body, $3 = acting identity login.
+gitea_create_comment_verified() {
+    local pr_number="$1" comment_body="$2" acting_login="$3"
+    local payload write_file readback_file write_status readback_status created_id
 
-    host=$(get_remote_host)
-    token=$(get_gitea_token "$host") || {
-        echo "Error: Gitea token not found for comment persistence" >&2
-        return 1
-    }
-    configured_url=$(get_gitea_url_for_host "$host") || {
-        echo "Error: Configured Gitea URL not found for comment persistence" >&2
-        return 1
-    }
-    repo=$(get_gitea_repo_slug_for_url "$configured_url") || {
-        echo "Error: Could not resolve Gitea owner/repository relative to configured URL" >&2
-        return 1
-    }
-    api_base="${configured_url%/}/api/v1/repos/$repo"
     payload=$(COMMENT_BODY="$comment_body" python3 -c '
 import json
 import os
 
 print(json.dumps({"body": os.environ["COMMENT_BODY"]}))
 ')
-    write_response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-write.XXXXXX")
-    readback_response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-readback.XXXXXX")
-    trap 'rm -f "$write_response_file" "$readback_response_file"' RETURN
+    write_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-write.XXXXXX")
+    readback_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-getid.XXXXXX")
+    trap 'rm -f "$write_file" "$readback_file"' RETURN
 
-    if ! write_status=$(curl -sS -o "$write_response_file" -w '%{http_code}' \
+    if ! write_status=$(curl -sS -o "$write_file" -w '%{http_code}' \
         -X POST \
-        -H "Authorization: token $token" \
+        -H "Authorization: token $GITEA_API_TOKEN" \
         -H 'Content-Type: application/json' \
         -d "$payload" \
-        "$api_base/issues/$pr_number/comments"); then
+        "$GITEA_API_BASE/issues/$pr_number/comments"); then
         echo "Error: Gitea comment write transport failed" >&2
         return 1
     fi
@@ -126,26 +116,26 @@ print(json.dumps({"body": os.environ["COMMENT_BODY"]}))
         return 1
     fi
 
-    comment_id=$(python3 - "$write_response_file" <<'PY'
+    created_id=$(python3 - "$write_file" <<'PY'
 import json
 import sys
 
 try:
     with open(sys.argv[1], encoding="utf-8") as response:
         comment = json.load(response)
-    comment_id = comment.get("id") if isinstance(comment, dict) else None
-    if not isinstance(comment_id, int) or comment_id <= 0:
-        raise ValueError("missing positive comment id")
+    created_id = comment.get("id") if isinstance(comment, dict) else None
+    if not isinstance(created_id, int) or created_id <= 0:
+        raise ValueError("create response carried no positive comment id")
 except (OSError, json.JSONDecodeError, ValueError) as error:
     print(f"Error: could not identify created Gitea comment: {error}", file=sys.stderr)
     raise SystemExit(1)
-print(comment_id)
+print(created_id)
 PY
 ) || return 1
 
-    if ! readback_status=$(curl -sS -o "$readback_response_file" -w '%{http_code}' \
-        -H "Authorization: token $token" \
-        "$api_base/issues/comments/$comment_id"); then
+    if ! readback_status=$(curl -sS -o "$readback_file" -w '%{http_code}' \
+        -H "Authorization: token $GITEA_API_TOKEN" \
+        "$GITEA_API_BASE/issues/comments/$created_id"); then
         echo "Error: Gitea comment read-back transport failed" >&2
         return 1
     fi
@@ -154,8 +144,10 @@ PY
         return 1
     fi
 
-    if EXPECTED_COMMENT_ID="$comment_id" EXPECTED_COMMENT_BODY="$comment_body" EXPECTED_REPO="$repo" EXPECTED_PR_NUMBER="$pr_number" \
-        python3 - "$readback_response_file" <<'PY'
+    EXPECTED_COMMENT_ID="$created_id" EXPECTED_COMMENT_BODY="$comment_body" \
+        ACTING_LOGIN="$acting_login" EXPECTED_REPO_SLUG="${GITEA_API_BASE##*/repos/}" \
+        EXPECTED_PR_NUMBER="$pr_number" \
+        python3 - "$readback_file" <<'PY' || return 1
 import json
 import os
 import sys
@@ -168,40 +160,48 @@ try:
         raise ValueError("response is not a comment object")
     expected_id = int(os.environ["EXPECTED_COMMENT_ID"])
     expected_body = os.environ["EXPECTED_COMMENT_BODY"]
-    expected_repo = os.environ["EXPECTED_REPO"]
-    expected_pr = os.environ["EXPECTED_PR_NUMBER"]
+    acting_login = os.environ["ACTING_LOGIN"]
+    expected_suffix = (
+        f"/repos/{os.environ['EXPECTED_REPO_SLUG']}"
+        f"/issues/{os.environ['EXPECTED_PR_NUMBER']}"
+    )
     issue_path = urlparse(comment.get("issue_url", "")).path.rstrip("/")
-    expected_suffix = f"/repos/{expected_repo}/issues/{expected_pr}"
     if comment.get("id") != expected_id:
-        raise ValueError("comment id mismatch")
+        raise ValueError("read-back id does not match the created id")
+    if (comment.get("user") or {}).get("login") != acting_login:
+        raise ValueError("created comment is not authored by the acting identity")
     if comment.get("body") != expected_body:
-        raise ValueError("comment body mismatch")
+        raise ValueError("created comment body does not match")
     if not issue_path.endswith(expected_suffix):
-        raise ValueError("repository or PR mismatch")
+        raise ValueError("created comment does not belong to this PR")
 except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as error:
     print(f"Error: Gitea comment persistence verification failed: {error}", file=sys.stderr)
     raise SystemExit(1)
 PY
-    then
-        true
-    else
-        return 1
-    fi
 
-    echo "$comment_id"
+    echo "$created_id"
     return 0
 }
 
-# Resolve and cache the Gitea REST endpoint + token for the current remote.
-# 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
+# Resolve and cache the Gitea REST endpoint + token for the current remote,
+# bound to a SPECIFIC login identity ($1). Populates GITEA_API_ROOT (…/api/v1),
+# GITEA_API_BASE (…/api/v1/repos/<slug>), and GITEA_API_TOKEN.
+#
+# The token is resolved for the EFFECTIVE login (the --login override when
+# given, otherwise the detected default), so the one credential used to submit
+# the review/comment ALSO drives the /user identity read and every read-back —
+# write token and read-back token are the same identity by construction. This
+# is the credential-ordering fix: a --login override is no longer submitted
+# under one credential and verified under a different default one. Falls back to
+# the host-scoped credential only when the login has no token in tea's config.
+# Returns non-zero (clear stderr) on any resolution failure.
+gitea_resolve_api_for_login() {
+    local effective_login="$1" host configured_url repo
 
     host=$(get_remote_host)
-    GITEA_API_TOKEN=$(get_gitea_token "$host") || {
-        echo "Error: Gitea token not found for review read-back verification" >&2
+    GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login") \
+        || GITEA_API_TOKEN=$(get_gitea_token "$host") || {
+        echo "Error: Gitea token not found for login '$effective_login' (review write/read-back)" >&2
         return 1
     }
     configured_url=$(get_gitea_url_for_host "$host") || {
@@ -311,65 +311,17 @@ 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
+# Resolve the PR's current head commit SHA (GET /pulls/{n}). The review is
+# submitted against — and later verified as pinned to — this exact commit, so a
+# stale review left over from an earlier push cannot be mistaken for this one.
+# Prints the head SHA on success.
+gitea_pr_head_sha() {
+    local pr_number="$1" pr_file status
 
-    merged_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-boundary.XXXXXX")
-    trap 'rm -f "$merged_file"' RETURN
+    pr_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-head.XXXXXX")
+    trap 'rm -f "$pr_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)
-    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:
-    print(f"Error: could not compute Gitea review boundary: {error}", file=sys.stderr)
-    raise SystemExit(1)
-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 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, $4 = acting reviewer login.
-gitea_verify_review_submitted() {
-    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_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}' \
+    if ! status=$(curl -sS -o "$pr_file" -w '%{http_code}' \
         -H "Authorization: token $GITEA_API_TOKEN" \
         "$GITEA_API_BASE/pulls/$pr_number"); then
         echo "Error: Gitea PR head read transport failed" >&2
@@ -379,7 +331,7 @@ gitea_verify_review_submitted() {
         echo "Error: Gitea PR head read failed with HTTP $status" >&2
         return 1
     fi
-    head_sha=$(python3 - "$pr_response_file" <<'PY'
+    python3 - "$pr_file" <<'PY'
 import json
 import sys
 
@@ -394,12 +346,25 @@ except (OSError, json.JSONDecodeError, AttributeError, TypeError, ValueError) as
     raise SystemExit(1)
 print(head_sha)
 PY
-) || return 1
+}
 
-    gitea_fetch_all "$GITEA_API_BASE/pulls/$pr_number/reviews" "$reviews_merged_file" || return 1
+# Confirm that the review CREATED by this action ($2 = its provider id) is
+# enumerable in the PR's full, paginated review listing, authored by the acting
+# identity, in the expected state. Gitea paginates review lists, so a review
+# created beyond page 1 must still be found; walking every page also proves the
+# created id is durably indexed against THIS PR rather than merely retrievable
+# by id. Returns non-zero (clear stderr) if the exact created id is absent or
+# does not match author/state.
+gitea_confirm_review_enumerable() {
+    local pr_number="$1" created_id="$2" expected_state="$3" acting_login="$4" merged_file
 
-    review_id=$(EXPECTED_STATE="$expected_state" BOUNDARY_REVIEW_ID="$boundary" EXPECTED_HEAD_SHA="$head_sha" ACTING_LOGIN="$acting_login" \
-        python3 - "$reviews_merged_file" <<'PY'
+    merged_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-list.XXXXXX")
+    trap 'rm -f "$merged_file"' RETURN
+
+    gitea_fetch_all "$GITEA_API_BASE/pulls/$pr_number/reviews" "$merged_file" || return 1
+
+    CREATED_REVIEW_ID="$created_id" EXPECTED_STATE="$expected_state" ACTING_LOGIN="$acting_login" \
+        python3 - "$merged_file" <<'PY'
 import json
 import os
 import sys
@@ -409,38 +374,138 @@ try:
         reviews = json.load(response)
     if not isinstance(reviews, list):
         raise ValueError("response is not a review list")
+    created_id = int(os.environ["CREATED_REVIEW_ID"])
     expected_state = os.environ["EXPECTED_STATE"]
-    boundary = int(os.environ["BOUNDARY_REVIEW_ID"])
-    expected_head = os.environ["EXPECTED_HEAD_SHA"]
     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:
+    match = next(
+        (
+            r for r in reviews
+            if isinstance(r, dict)
+            and r.get("id") == created_id
+            and (r.get("user") or {}).get("login") == acting_login
+            and r.get("state") == expected_state
+        ),
+        None,
+    )
+    if match is None:
         raise ValueError(
-            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)"
+            f"created review id {created_id} is not enumerable in the PR's "
+            "paginated review list under the acting identity/state"
         )
-    review_id = max(r["id"] for r in matches)
 except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as error:
-    print(f"Error: Gitea review persistence verification failed: {error}", file=sys.stderr)
+    print(f"Error: Gitea review enumeration check failed: {error}", file=sys.stderr)
     raise SystemExit(1)
-print(review_id)
+PY
+}
+
+# Submit a review to a Gitea PR via the supported REST API and verify it against
+# a PROVIDER-RETURNED created id. tea 0.11.1's `pr approve`/`reject` cannot emit
+# the id of the review it created and can silently no-op while exiting 0 (#865
+# defect class), so this does NOT shell out to tea: it POSTs to
+# /pulls/{n}/reviews with the event (APPROVED / REQUEST_CHANGES), the PR head
+# commit_id, and the review body, which returns the created review object
+# including its id. It then GETs that exact review id and requires
+# id == created id AND author == acting identity AND state == expected AND
+# commit_id == PR head. Keying to the returned id means no concurrent review
+# (even same identity/state/head) can masquerade as this one, and a no-op
+# submit yields no id and fails closed. Prints the created review id on success.
+#
+# Args: $1 = PR number, $2 = event (APPROVED|REQUEST_CHANGES),
+#       $3 = review body (may be empty for APPROVED), $4 = acting login,
+#       $5 = PR head sha.
+gitea_submit_review_verified() {
+    local pr_number="$1" event="$2" review_body="$3" acting_login="$4" head_sha="$5"
+    local payload write_file readback_file write_status readback_status created_id
+
+    payload=$(REVIEW_EVENT="$event" REVIEW_BODY="$review_body" REVIEW_COMMIT="$head_sha" python3 -c '
+import json
+import os
+
+print(json.dumps({
+    "event": os.environ["REVIEW_EVENT"],
+    "body": os.environ["REVIEW_BODY"],
+    "commit_id": os.environ["REVIEW_COMMIT"],
+}))
+')
+    write_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-submit.XXXXXX")
+    readback_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-getid.XXXXXX")
+    trap 'rm -f "$write_file" "$readback_file"' RETURN
+
+    if ! write_status=$(curl -sS -o "$write_file" -w '%{http_code}' \
+        -X POST \
+        -H "Authorization: token $GITEA_API_TOKEN" \
+        -H 'Content-Type: application/json' \
+        -d "$payload" \
+        "$GITEA_API_BASE/pulls/$pr_number/reviews"); then
+        echo "Error: Gitea review submit transport failed" >&2
+        return 1
+    fi
+    # Gitea returns 200 (occasionally 201) with the created review object.
+    if [[ "$write_status" != "200" && "$write_status" != "201" ]]; then
+        echo "Error: Gitea review submit failed with HTTP $write_status (#865: no durable review created)" >&2
+        return 1
+    fi
+
+    created_id=$(python3 - "$write_file" <<'PY'
+import json
+import sys
+
+try:
+    with open(sys.argv[1], encoding="utf-8") as response:
+        review = json.load(response)
+    created_id = review.get("id") if isinstance(review, dict) else None
+    if not isinstance(created_id, int) or created_id <= 0:
+        raise ValueError("submit response carried no positive review id")
+except (OSError, json.JSONDecodeError, ValueError) as error:
+    print(f"Error: could not identify created Gitea review: {error}", file=sys.stderr)
+    raise SystemExit(1)
+print(created_id)
 PY
 ) || return 1
 
-    echo "$review_id"
+    if ! readback_status=$(curl -sS -o "$readback_file" -w '%{http_code}' \
+        -H "Authorization: token $GITEA_API_TOKEN" \
+        "$GITEA_API_BASE/pulls/$pr_number/reviews/$created_id"); then
+        echo "Error: Gitea review read-back transport failed" >&2
+        return 1
+    fi
+    if [[ "$readback_status" != "200" ]]; then
+        echo "Error: Gitea review read-back failed with HTTP $readback_status" >&2
+        return 1
+    fi
+
+    EXPECTED_REVIEW_ID="$created_id" EXPECTED_STATE="$event" ACTING_LOGIN="$acting_login" \
+        EXPECTED_HEAD_SHA="$head_sha" \
+        python3 - "$readback_file" <<'PY' || return 1
+import json
+import os
+import sys
+
+try:
+    with open(sys.argv[1], encoding="utf-8") as response:
+        review = json.load(response)
+    if not isinstance(review, dict):
+        raise ValueError("response is not a review object")
+    expected_id = int(os.environ["EXPECTED_REVIEW_ID"])
+    expected_state = os.environ["EXPECTED_STATE"]
+    acting_login = os.environ["ACTING_LOGIN"]
+    expected_head = os.environ["EXPECTED_HEAD_SHA"]
+    if review.get("id") != expected_id:
+        raise ValueError("read-back id does not match the created id")
+    if (review.get("user") or {}).get("login") != acting_login:
+        raise ValueError("created review is not authored by the acting identity")
+    if review.get("state") != expected_state:
+        raise ValueError("created review is not in the expected state")
+    if review.get("commit_id") != expected_head:
+        raise ValueError("created review is not pinned to the PR head commit")
+except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as error:
+    print(f"Error: Gitea review persistence verification failed: {error}", file=sys.stderr)
+    raise SystemExit(1)
+PY
+
+    gitea_confirm_review_enumerable "$pr_number" "$created_id" "$event" "$acting_login" || return 1
+
+    echo "$created_id"
     return 0
 }
 
@@ -474,74 +539,76 @@ if [[ "$PLATFORM" == "github" ]]; then
 elif [[ "$PLATFORM" == "gitea" ]]; then
     case $ACTION in
         approve)
-            repo=$(get_repo_slug)
             host=$(get_remote_host)
-            login=$(get_gitea_login_for_host "$host")
-            # Resolve the REST endpoint and record the pre-write review-id
-            # boundary BEFORE the write, so the read-back can require a
-            # 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
+            # A --login override always wins. Otherwise name this host's login
+            # only as a best effort: the login name merely selects a per-login
+            # token, and gitea_resolve_api_for_login falls back to the host
+            # credential (get_gitea_token) when no tea login is named — so a host
+            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the default credential to resolve. The single resolved token is
+            # then used for the write, the /user identity, and the read-back.
+            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
+            # Bind the REST endpoint + token to the effective login, then derive
+            # the acting identity from that SAME credential so the review submit
+            # and its read-back verify against the identity that performed them.
+            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" || 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).
-            TEA_ARGS=(pr approve "$PR_NUMBER" --repo "$repo" --login "$login")
-            # --login override goes LAST: tea honors only the final --login on
-            # its command line, so an override placed before the detected
-            # default above would be silently clobbered by it.
-            if [[ -n "$LOGIN_OVERRIDE" ]]; then
-                TEA_ARGS+=(--login "$LOGIN_OVERRIDE")
-            fi
-            tea "${TEA_ARGS[@]}"
-            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
+            head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
+            # The review body (if any) travels with the review itself in the REST
+            # submit — the created review record carries it — so there is no
+            # separate detached comment to reconcile.
+            review_id=$(gitea_submit_review_verified "$PR_NUMBER" "APPROVED" "$COMMENT" "$ACTING_LOGIN" "$head_sha") || {
+                echo "Error: could not submit and verify an APPROVED review on Gitea PR #$PR_NUMBER via a provider-returned created id (#865)." >&2
                 exit 1
             }
             echo "Approved and verified Gitea PR #$PR_NUMBER (review ID $review_id)"
-            if [[ -n "$COMMENT" ]]; then
-                comment_id=$(gitea_post_verified_comment "$PR_NUMBER" "$COMMENT") || exit 1
-                echo "Added and verified review comment on Gitea PR #$PR_NUMBER (comment ID $comment_id)"
-            fi
             ;;
         request-changes)
             if [[ -z "$COMMENT" ]]; then
                 echo "Error: Comment required for request-changes"
                 exit 1
             fi
-            repo=$(get_repo_slug)
             host=$(get_remote_host)
-            login=$(get_gitea_login_for_host "$host")
-            # Record the pre-write review-id boundary BEFORE the write (see the
-            # approve path above for the rationale).
-            gitea_resolve_api || exit 1
+            # A --login override always wins. Otherwise name this host's login
+            # only as a best effort: the login name merely selects a per-login
+            # token, and gitea_resolve_api_for_login falls back to the host
+            # credential (get_gitea_token) when no tea login is named — so a host
+            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the default credential to resolve. The single resolved token is
+            # then used for the write, the /user identity, and the read-back.
+            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
+            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" || 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).
-            TEA_ARGS=(pr reject "$PR_NUMBER" --repo "$repo" --login "$login")
-            # --login override goes LAST: tea honors only the final --login on
-            # its command line, so an override placed before the detected
-            # default above would be silently clobbered by it.
-            if [[ -n "$LOGIN_OVERRIDE" ]]; then
-                TEA_ARGS+=(--login "$LOGIN_OVERRIDE")
-            fi
-            tea "${TEA_ARGS[@]}"
-            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
+            head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
+            review_id=$(gitea_submit_review_verified "$PR_NUMBER" "REQUEST_CHANGES" "$COMMENT" "$ACTING_LOGIN" "$head_sha") || {
+                echo "Error: could not submit and verify a REQUEST_CHANGES review on Gitea PR #$PR_NUMBER via a provider-returned created id (#865)." >&2
                 exit 1
             }
             echo "Requested changes and verified on Gitea PR #$PR_NUMBER (review ID $review_id)"
-            comment_id=$(gitea_post_verified_comment "$PR_NUMBER" "$COMMENT") || exit 1
-            echo "Added and verified review comment on Gitea PR #$PR_NUMBER (comment ID $comment_id)"
             ;;
         comment)
             if [[ -z "$COMMENT" ]]; then
                 echo "Error: Comment required"
                 exit 1
             fi
-
-            comment_id=$(gitea_post_verified_comment "$PR_NUMBER" "$COMMENT") || exit 1
+            host=$(get_remote_host)
+            # A --login override always wins. Otherwise name this host's login
+            # only as a best effort: the login name merely selects a per-login
+            # token, and gitea_resolve_api_for_login falls back to the host
+            # credential (get_gitea_token) when no tea login is named — so a host
+            # tea's login list need not enumerate exotic (e.g. ported) hosts for
+            # the default credential to resolve. The single resolved token is
+            # then used for the write, the /user identity, and the read-back.
+            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
+            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
+            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" || exit 1
+            ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
+            comment_id=$(gitea_create_comment_verified "$PR_NUMBER" "$COMMENT" "$ACTING_LOGIN") || {
+                echo "Error: could not create and verify a comment on Gitea PR #$PR_NUMBER via a provider-returned created id (#865)." >&2
+                exit 1
+            }
             echo "Added and verified comment on Gitea PR #$PR_NUMBER (comment ID $comment_id)"
             ;;
         *)