fix(tools): bound Gitea read-back to this write; verify approve/reject state (#865)

Review remediation for two correctness holes in the #865 fix:

BLOCKER 1 — issue-comment.sh read-back was body-only across all history:
if `tea comment` silently no-opped (the #865 bug) while an identically
bodied comment already existed from a prior run, the read-back matched the
OLD comment and falsely reported success. Now record the pre-write maximum
comment id as a boundary and require a comment with id > boundary AND exact
body match; monotonic Gitea ids make id > boundary mean "created by this
write". Fails closed otherwise.

BLOCKER 2 — pr-review.sh approve/reject trusted tea's exit code for the
review STATE (same never-trust-exit-zero defect class as #865). Removed the
TODO deferral and added a real bounded read-back: record the max review id
before `tea pr approve`/`reject`, then require a review with id > boundary,
the expected state (APPROVED / REQUEST_CHANGES), and commit_id equal to the
PR's current head. Fails closed if absent.

Tests: extended test-pr-review-gitea-comment.sh to model and assert the new
review-state read-back (guardrails preserved, assertions added). Added
test-issue-comment-readback.sh proving the pre-existing-identical-body
false positive now fails closed and a genuinely new comment verifies.

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

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -72,16 +72,14 @@ fi
 
 detect_platform >/dev/null
 
-# Independently re-fetch the issue's comments via the Gitea REST API and
-# confirm one matches the body we just posted (see header comment: tea's
-# exit code is not trustworthy evidence of a durable write on its own).
-# Prints the matched comment ID to stdout on success.
-gitea_verify_comment_posted() {
-    local issue_number="$1" comment_body="$2"
-    local host token configured_url repo api_base readback_response_file
+# 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.
+gitea_resolve_api() {
+    local host configured_url repo
 
     host=$(get_remote_host)
-    token=$(get_gitea_token "$host") || {
+    GITEA_API_TOKEN=$(get_gitea_token "$host") || {
         echo "Error: Gitea token not found for comment read-back verification" >&2
         return 1
     }
@@ -93,23 +91,76 @@ gitea_verify_comment_posted() {
         echo "Error: Could not resolve Gitea owner/repository relative to configured URL" >&2
         return 1
     }
-    api_base="${configured_url%/}/api/v1/repos/$repo"
+    GITEA_API_BASE="${configured_url%/}/api/v1/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
+
+    response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-issue-comment-boundary.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
+        return 1
+    fi
+    if [[ "$status" != "200" ]]; then
+        echo "Error: Gitea comment boundary read failed with HTTP $status" >&2
+        return 1
+    fi
+
+    python3 - "$response_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:
+    print(f"Error: could not compute Gitea comment boundary: {error}", file=sys.stderr)
+    raise SystemExit(1)
+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.
+gitea_verify_comment_posted() {
+    local issue_number="$1" comment_body="$2" boundary="$3"
+    local readback_response_file status
 
     readback_response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-issue-comment-readback.XXXXXX")
     trap 'rm -f "$readback_response_file"' RETURN
 
-    if ! readback_status=$(curl -sS -o "$readback_response_file" -w '%{http_code}' \
-        -H "Authorization: token $token" \
-        "$api_base/issues/$issue_number/comments"); then
+    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 [[ "$readback_status" != "200" ]]; then
-        echo "Error: Gitea comment read-back failed with HTTP $readback_status" >&2
+    if [[ "$status" != "200" ]]; then
+        echo "Error: Gitea comment read-back failed with HTTP $status" >&2
         return 1
     fi
 
-    EXPECTED_COMMENT_BODY="$comment_body" python3 - "$readback_response_file" <<'PY'
+    EXPECTED_COMMENT_BODY="$comment_body" BOUNDARY_COMMENT_ID="$boundary" \
+        python3 - "$readback_response_file" <<'PY'
 import json
 import os
 import sys
@@ -120,13 +171,21 @@ try:
     if not isinstance(comments, list):
         raise ValueError("response is not a comment list")
     expected_body = os.environ["EXPECTED_COMMENT_BODY"]
-    matches = [c for c in comments if isinstance(c, dict) and c.get("body") == expected_body]
+    boundary = int(os.environ["BOUNDARY_COMMENT_ID"])
+    # Require both: created-after-boundary (fresh write) AND exact body match.
+    matches = [
+        c for c in comments
+        if isinstance(c, dict)
+        and isinstance(c.get("id"), int)
+        and c.get("id") > boundary
+        and c.get("body") == expected_body
+    ]
     if not matches:
-        raise ValueError("no matching comment found on read-back")
-    best = max(matches, key=lambda c: c.get("id") or 0)
-    comment_id = best.get("id")
-    if not isinstance(comment_id, int) or comment_id <= 0:
-        raise ValueError("matching comment has no usable id")
+        raise ValueError(
+            "no comment created by this write matched (id > boundary and exact body); "
+            "tea may have silently no-opped (#865)"
+        )
+    comment_id = max(c["id"] for c in matches)
 except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as error:
     print(f"Error: Gitea comment persistence verification failed: {error}", file=sys.stderr)
     raise SystemExit(1)
@@ -146,6 +205,12 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
         echo "Error: could not resolve a Gitea login for this repo; cannot comment on issue #$ISSUE_NUMBER." >&2
         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.
+    gitea_resolve_api || exit 1
+    boundary=$(gitea_max_comment_id "$ISSUE_NUMBER") || exit 1
+
     TEA_ARGS=(comment "$ISSUE_NUMBER" "$COMMENT" --repo "$REPO_SLUG" --login "$GITEA_LOGIN_NAME")
     # --login override goes LAST: tea honors only the final --login on its
     # command line, so an override placed before the detected default above
@@ -155,8 +220,8 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
     fi
     tea "${TEA_ARGS[@]}"
 
-    comment_id=$(gitea_verify_comment_posted "$ISSUE_NUMBER" "$COMMENT") || {
-        echo "Error: could not verify comment landed on Gitea issue #$ISSUE_NUMBER via read-back; treating tea's exit code as untrustworthy (#865)." >&2
+    comment_id=$(gitea_verify_comment_posted "$ISSUE_NUMBER" "$COMMENT" "$boundary") || {
+        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
     }
     echo "Added and verified comment on Gitea issue #$ISSUE_NUMBER (comment ID $comment_id)"