fix(framework): pr-review.sh -r/--repo + -H/--host overrides, UA header, repo preflight (Patch 5/5c)

Upstreams the pr-review.sh -r/--repo and -H/--host override family from the
host-local tooling-patches kit (patch 5 + 5c), adapted to the framework's
current REST-native review/comment implementation:

- -r/--repo <owner/repo>: explicit slug override, skipping git-remote slug
  inference, for reviewer worktrees whose origin is nonstandard or missing.
  Mirrors the established -r convention of the sibling wrappers (pr-view.sh,
  pr-diff.sh, pr-ci-wait.sh; #867). detect_platform is now tolerant of a
  missing/foreign git origin when -r is given (assumes gitea), matching the
  same sibling-wrapper convention.
- -H/--host <host>: explicit Gitea host override, skipping remote-host
  inference, so ambient CWD/remote state cannot cross-wire a review/comment to
  the wrong instance.
- Repo-exists preflight: when -r is used, GET .../repos/<slug> BEFORE any
  write. A wrong-host cross-wire now surfaces as a clear preflight error
  instead of an opaque write-404.
- `User-Agent: mosaic-pr-review` header added to every Gitea curl call (write,
  read-back, /user, PR-head read, preflight) — some Cloudflare-fronted Gitea
  hosts intermittently reject curl's default User-Agent.

Reproduce-first evidence (against origin/main baseline, fresh clone):
- -r/-H: `./pr-review.sh -n 1 -a comment -c x -r foo/bar` / `-H example.test`
  both failed with "Unknown option" pre-patch; both parse post-patch.
- User-Agent: `grep -c User-Agent pr-review.sh` was 0 pre-patch.
- New regression test (test-pr-review-repo-host-override.sh) fails against the
  baseline file and passes against the patched file (red-first confirmed).

Scope note — two sub-changes from the source kit's patch family (5b: an
issue_url-empty html_url readback fallback; 5d: REST-native reviews replacing
`tea approve/reject`) were investigated and found ALREADY SUPERSEDED on this
baseline by a more robust, already-tested implementation:
- 5d: the current gitea_submit_review_verified() already POSTs to
  /pulls/{n}/reviews (no `tea pr approve/reject` call exists in this file —
  `grep -c 'tea pr' pr-review.sh` is 0), with additional hardening (identity
  binding, PR-head commit pinning, current-head TOCTOU close-out) beyond what
  the source patch describes.
- 5b: comment verification already keys off `pull_request_url` (not
  `issue_url`) with full origin+path pinning (see gitea_create_comment_verified
  / test-pr-review-gitea-comment.sh cases 15b, 17), which already handles the
  Gitea empty-issue_url-on-PR-comments behavior the source patch targets, via a
  stricter mechanism than a bare html_url fallback would provide. Porting the
  source kit's simpler fallback verbatim would have been a regression.

Per HALT-on-no-repro discipline, only the two sub-changes that actually
reproduced against baseline (5, 5c) are included here.

Part of #891

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

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-review.sh - Review a pull request on GitHub or Gitea
-# Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>]
+# Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>] [-r owner/repo] [-H host]
 #
 # 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
@@ -16,6 +16,18 @@
 # 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.
+#
+# -r/--repo override: explicit owner/repo slug, skipping git-remote slug
+# inference — mirrors the -r convention of the sibling wrappers (pr-view.sh,
+# pr-diff.sh, pr-ci-wait.sh; mosaicstack/stack #867) for reviewer worktrees
+# whose origin is nonstandard or missing. -H/--host makes the target Gitea
+# instance explicit too (skips remote-host inference), so ambient CWD/remote
+# state can no longer cross-wire the review to the wrong instance. With -r, the
+# resolved repo is preflighted (GET .../repos/<slug>) BEFORE any write so a
+# wrong-host cross-wire surfaces as a clear preflight error instead of an opaque
+# write-404. Every Gitea curl (write, read-back, preflight) carries a
+# `User-Agent: mosaic-pr-review` header, since some Cloudflare-fronted Gitea
+# hosts intermittently reject curl's default User-Agent.
 
 set -e
 
@@ -28,6 +40,8 @@ PR_NUMBER=""
 ACTION=""
 COMMENT=""
 LOGIN_OVERRIDE=""
+REPO_OVERRIDE=""
+HOST_OVERRIDE=""
 
 while [[ $# -gt 0 ]]; do
     case $1 in
@@ -47,14 +61,24 @@ while [[ $# -gt 0 ]]; do
             LOGIN_OVERRIDE="$2"
             shift 2
             ;;
+        -r|--repo)
+            REPO_OVERRIDE="$2"
+            shift 2
+            ;;
+        -H|--host)
+            HOST_OVERRIDE="$2"
+            shift 2
+            ;;
         -h|--help)
-            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>]"
+            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>] [-r owner/repo] [-H host]"
             echo ""
             echo "Options:"
             echo "  -n, --number   PR number (required)"
             echo "  -a, --action   Review action: approve, request-changes, comment (required)"
             echo "  -c, --comment  Review comment (required for request-changes)"
             echo "  -l, --login    Override the detected Gitea tea login (approve/request-changes only)"
+            echo "  -r, --repo     Explicit owner/repo slug (skips git-remote slug inference)"
+            echo "  -H, --host     Explicit Gitea host (skips remote-host inference)"
             echo "  -h, --help     Show this help"
             exit 0
             ;;
@@ -75,7 +99,15 @@ if [[ -z "$ACTION" ]]; then
     exit 1
 fi
 
-detect_platform >/dev/null
+if [[ -n "$REPO_OVERRIDE" ]]; then
+    # An explicit --repo is the whole point of a reviewer worktree whose origin
+    # is nonstandard or missing (#867 convention, mirrored from pr-view.sh /
+    # pr-diff.sh): do not hard-fail platform detection on a missing/foreign
+    # origin — assume gitea, the only platform --repo/--host target.
+    detect_platform >/dev/null 2>&1 || PLATFORM="gitea"
+else
+    detect_platform >/dev/null
+fi
 
 # 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
@@ -110,6 +142,7 @@ print(json.dumps({"body": os.environ["COMMENT_BODY"]}))
     if ! write_status=$(curl -sS -o "$write_file" -w '%{http_code}' \
         -X POST \
         --config "$auth_config" \
+        -H 'User-Agent: mosaic-pr-review' \
         -H 'Content-Type: application/json' \
         -d "$payload" \
         "$GITEA_API_BASE/issues/$pr_number/comments"); then
@@ -140,6 +173,7 @@ PY
 
     if ! readback_status=$(curl -sS -o "$readback_file" -w '%{http_code}' \
         --config "$auth_config" \
+        -H 'User-Agent: mosaic-pr-review' \
         "$GITEA_API_BASE/issues/comments/$created_id"); then
         echo "Error: Gitea comment read-back transport failed" >&2
         return 1
@@ -245,10 +279,24 @@ PY
 # caller-supplied --login: that exact login's token MUST resolve, and we FAIL
 # CLOSED rather than silently downgrading the review/comment to the host default
 # identity. Returns non-zero (clear stderr) on any resolution failure.
+#
+# Honors the module-level REPO_OVERRIDE / HOST_OVERRIDE (-r/--repo, -H/--host):
+# when set, they skip git-remote slug/host inference entirely — for reviewer
+# worktrees whose origin is nonstandard or missing, and to make the target
+# instance fully deterministic (an ambient CWD/remote can otherwise cross-wire
+# a review to the wrong Gitea host). When -r/--repo is used, the resolved repo
+# is preflighted (GET .../repos/<slug>) BEFORE any write: a wrong-host
+# cross-wire would otherwise surface only as an opaque write-404 with zero
+# residue.
 gitea_resolve_api_for_login() {
     local effective_login="$1" override_explicit="${2:-}" host configured_url repo
+    local preflight_auth_config preflight_status
 
-    host=$(get_remote_host)
+    if [[ -n "$HOST_OVERRIDE" ]]; then
+        host="$HOST_OVERRIDE"
+    else
+        host=$(get_remote_host)
+    fi
     if [[ -n "$override_explicit" ]]; then
         GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login" "$host") || {
             echo "Error: could not resolve a host-matched Gitea token for --login '$effective_login' on host '$host'; refusing to fall back to the host default identity or a cross-host credential (review write/read-back)" >&2
@@ -265,10 +313,14 @@ gitea_resolve_api_for_login() {
         echo "Error: Configured Gitea URL not found for review read-back verification" >&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
-    }
+    if [[ -n "$REPO_OVERRIDE" ]]; then
+        repo="$REPO_OVERRIDE"
+    else
+        repo=$(get_gitea_repo_slug_for_url "$configured_url") || {
+            echo "Error: Could not resolve Gitea owner/repository relative to configured URL" >&2
+            return 1
+        }
+    fi
     GITEA_API_ROOT="${configured_url%/}/api/v1"
     GITEA_API_BASE="$GITEA_API_ROOT/repos/$repo"
     # The provider WEB base (scheme + host + effective port + any deployment path
@@ -276,6 +328,22 @@ gitea_resolve_api_for_login() {
     # Read-back verification pins the returned URL's origin + path prefix to THIS,
     # not just a repo/PR suffix.
     GITEA_WEB_BASE="${configured_url%/}"
+
+    if [[ -n "$REPO_OVERRIDE" ]]; then
+        preflight_auth_config=$(gitea_write_auth_config "$GITEA_API_TOKEN") || {
+            echo "Error: could not stage Gitea credential for --repo preflight" >&2
+            return 1
+        }
+        preflight_status=$(curl -sS -o /dev/null -w '%{http_code}' \
+            --config "$preflight_auth_config" \
+            -H 'User-Agent: mosaic-pr-review' \
+            "$GITEA_API_BASE") || preflight_status="000"
+        rm -f "$preflight_auth_config"
+        if [[ "$preflight_status" != "200" ]]; then
+            echo "Error: repo '$repo' not reachable at $configured_url (HTTP $preflight_status) — wrong host? pass -H/--host <gitea-host> or cd into the target checkout" >&2
+            return 1
+        fi
+    fi
     return 0
 }
 
@@ -296,6 +364,7 @@ gitea_authenticated_login() {
 
     if ! status=$(curl -sS -o "$response_file" -w '%{http_code}' \
         --config "$auth_config" \
+        -H 'User-Agent: mosaic-pr-review' \
         "$GITEA_API_ROOT/user"); then
         echo "Error: Gitea authenticated-identity read transport failed" >&2
         return 1
@@ -332,6 +401,7 @@ gitea_read_pr_head_into() {
 
     if ! status=$(curl -sS -o "$pr_file" -w '%{http_code}' \
         --config "$auth_config" \
+        -H 'User-Agent: mosaic-pr-review' \
         "$GITEA_API_BASE/pulls/$pr_number"); then
         echo "Error: Gitea PR head read transport failed" >&2
         return 1
@@ -418,6 +488,7 @@ print(json.dumps({
     if ! write_status=$(curl -sS -o "$write_file" -w '%{http_code}' \
         -X POST \
         --config "$auth_config" \
+        -H 'User-Agent: mosaic-pr-review' \
         -H 'Content-Type: application/json' \
         -d "$payload" \
         "$GITEA_API_BASE/pulls/$pr_number/reviews"); then
@@ -449,6 +520,7 @@ PY
 
     if ! readback_status=$(curl -sS -o "$readback_file" -w '%{http_code}' \
         --config "$auth_config" \
+        -H 'User-Agent: mosaic-pr-review' \
         "$GITEA_API_BASE/pulls/$pr_number/reviews/$created_id"); then
         echo "Error: Gitea review read-back transport failed" >&2
         return 1