fix(ci): accept the override from a PR review, and stop misdiagnosing an unreadable comments API

The override did not work on its first real test, and the reason was invisible
from the outside. Run 203 on PR #38: a well-formed `/approve-override` posted by
jakman85 in the PR comment box, 29 minutes newer than the head commit, and the
stage still blocked with:

    approval-override: COMMENTS_JSON is not a list

SETTINGS_API_TOKEN is minted [read:repository, read:admin], and Gitea puts
/issues/{n}/comments behind the *issue* scope — so Gitea answered with an error
OBJECT, `jq -e .` accepted it as valid JSON, and the stage fell through to 'no
approving review'. A permission failure wearing the costume of a missing
override. /pulls/{n}/files and /pulls/{n}/reviews are under read:repository,
which is why every other part of the same stage worked.

1. The diagnosis no longer lies. COMMENTS_JSON leaves the must-parse-or-block
   loop and is checked for being an ARRAY; when it is not, the stage prints
   Gitea's own .message, names the missing scope and says where to post instead.
   An unreadable source can only cause a false BLOCK, never a false pass, so a
   loud warning is the honest behaviour and blocking was not.
2. An override is accepted from a PR REVIEW body as well as a comment, so the
   hatch is not hostage to one API scope — a review of type 'Comment' works on
   the token CI has today. The gate names which source it used; PENDING
   (unsubmitted, author-only) reviews are dropped.
3. set-ci-token.sh requests read:issue, making the ordinary comment box work —
   on a RE-RUN only, since an existing token's scopes cannot be widened.

ci/tests/approval-override.test.sh: 23 -> 38 assertions, covering the reviews
source, PENDING reviews, an error object from the comments API, 'an unreadable
comments source must not suppress a valid review override', latest-wins across
both sources, and that the diagnostic quotes Gitea's message.

Also measured and recorded: run 203 shows gitea-settings PASS after the operator
ran the live PATCH, with block_admin_merge_override still true — the narrow
change held, the approval count moved and the gate's teeth did not.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

CLAUDE.md

@@ -40,13 +40,21 @@ missing credential is a lock-out, here a skip would be a bypass.
 **The administrator override (2026-10-01).** The rule above was unsatisfiable for the one human
 who runs this repo: Gitea refuses to let an author approve their own PR, and `jakman85` is the
 only collaborator — so a sensitive-path PR the operator opened could never be merged, *including
-the PR that would fix that.* An administrator may therefore waive the review by commenting on
+the PR that would fix that.* An administrator may therefore waive the review by posting this on
 the PR:
 
     /approve-override <reason>
 
-The directive must **start a line**, the **reason is mandatory**, the commenter's `admin`/`owner`
-permission is re-checked **live** when the gate runs, and the comment must be **newer than the
+**Post it as a PR *review* of type "Comment", not in the plain comment box.** CI's
+`SETTINGS_API_TOKEN` is minted `[read:repository, read:admin]`, and `/issues/{n}/comments` sits
+behind Gitea's *issue* scope — so an override typed into the comment box is **invisible to CI**,
+and the stage reports it as a missing approval rather than as a permission problem (measured on
+PR #38, 2026-10-02). `/pulls/{n}/reviews` is readable, so a review body works today. Both sources
+are accepted and the gate names which it used; the comment box starts working once
+`infra/gitea/set-ci-token.sh` is re-run to pick up `read:issue`.
+
+The directive must **start a line**, the **reason is mandatory**, the poster's `admin`/`owner`
+permission is re-checked **live** when the gate runs, and it must be **newer than the
 head commit** — push again and you must override again. The overrider, the timestamp and the
 reason are printed in the gate log and the job summary. For an administrator, "a change to the
 gate cannot be gated by the gate" is therefore **advisory, not structural**; what is kept is an

ci/approval-override.py

@@ -1,39 +1,54 @@
 #!/usr/bin/env python3
-"""ci/approval-override.py — select the admin-override comment on a PR, if there is a valid one.
+"""ci/approval-override.py — select the admin-override on a PR, if there is a valid one.
 
-This script decides NOTHING about authority. It parses a PR's comment list and returns the
-single override *candidate* that ci/approval-policy.sh should then try to authorise against
+This script decides NOTHING about authority. It parses a PR's comments and reviews and returns
+the single override *candidate* that ci/approval-policy.sh should then try to authorise against
 the live Gitea permission API. Keeping the two apart is the point:
 
   * parsing is pure, offline, and therefore TESTABLE (ci/tests/approval-override.test.sh);
   * authorisation needs the API and must stay in the stage that fails closed.
 
-A candidate is a comment whose body contains, AT THE START OF A LINE, the directive followed
-by a non-empty reason:
+A candidate is a comment OR a review whose body contains, AT THE START OF A LINE, the directive
+followed by a non-empty reason:
 
     /approve-override the gate cannot gate itself and I am the only human reviewer
 
+TWO SOURCES, AND WHY THAT IS NOT BELT-AND-BRACES. Measured 2026-10-02 on PR #38: the override was
+posted as an ordinary PR comment, was well-formed, was newer than the head commit — and the stage
+still blocked, because CI could not READ it. `SETTINGS_API_TOKEN` is minted with scopes
+`[read:repository, read:admin]`, and Gitea puts /issues/{n}/comments behind the *issue* scope, so
+the request came back as an error OBJECT rather than an array. `/pulls/{n}/reviews` is under
+read:repository and was readable in the same run. So:
+
+  * a REVIEW body works with the token CI has today (leave a review of type "Comment");
+  * a COMMENT body works once the token carries read:issue (see infra/gitea/set-ci-token.sh).
+
+Accepting both means the hatch is not hostage to one API scope. A source that cannot be read
+contributes no candidates and is reported on stderr; it can only cause a false BLOCK, never a
+false pass, which is why degrading it is safe and blocking on it was not necessary.
+
 WHY EACH RULE IS HERE
 
   * START OF A LINE, not "anywhere in the body". Otherwise quoting someone else's override
-    ("you could just /approve-override this") re-arms it. Markdown quotes are stripped of a
-    leading '>' before matching for the same reason -- a quoted directive must NOT count, so
-    lines beginning with '>' are DROPPED, not unquoted.
-  * A REASON IS MANDATORY. A bare directive records that a review was waived but not why,
-    which is the difference between an audit trail and a rubber stamp.
-  * STALE OVERRIDES ARE DISCARDED. An override earned at commit A must not silently cover
-    commit B. Any candidate created at or before the head commit's timestamp is dropped --
-    the same semantics Gitea's own `dismiss_stale_approvals` applies to reviews. Push new
-    commits and you must re-override.
-  * THE LATEST CANDIDATE WINS, so a second override comment supersedes the first rather than
-    both being live.
+    ("you could just /approve-override this") re-arms it. Lines beginning with '>' are DROPPED
+    rather than unquoted, for exactly that reason.
+  * A REASON IS MANDATORY. A bare directive records that a review was waived but not why, which
+    is the difference between an audit trail and a rubber stamp.
+  * STALE OVERRIDES ARE DISCARDED. An override earned at commit A must not silently cover commit
+    B. Any candidate created at or before the head commit's timestamp is dropped — the same
+    semantics Gitea's own `dismiss_stale_approvals` applies to approvals. Push new commits and
+    you must re-override.
+  * A PENDING REVIEW IS NOT SUBMITTED. It is a private draft visible only to its author, so it is
+    not an act of anything and is dropped.
+  * THE LATEST CANDIDATE WINS, across both sources, so a later override supersedes an earlier one.
 
-Output: one TSV line (login, created_at, reason) on stdout, or nothing at all when there is no
-valid candidate. Never exits non-zero for "no override" -- absence is a normal answer, and the
+Output: one TSV line (login, timestamp, source, reason) on stdout, or nothing at all when there is
+no valid candidate. Never exits non-zero for "no override" — absence is a normal answer and the
 caller must not be able to confuse it with a parse crash.
 
 Input, all via env so nothing lands in `ps`:
-  COMMENTS_JSON  the Gitea /issues/{n}/comments array
+  COMMENTS_JSON  the Gitea /issues/{n}/comments array (or an error object; or absent)
+  REVIEWS_JSON   the Gitea /pulls/{n}/reviews array   (or an error object; or absent)
   HEAD_TIME      ISO-8601 timestamp of the PR head commit
   DIRECTIVE      the override directive, e.g. /approve-override
 """
@@ -81,57 +96,97 @@ def extract_reason(body, directive):
     return None
 
 
-def main():
-    directive = os.environ.get("DIRECTIVE", "/approve-override").strip()
-    head_time = parse_ts(os.environ.get("HEAD_TIME", ""))
-
+def load_source(env_name, label):
+    """Return a list of items for one source, or [] with a stderr note if it is unusable."""
+    raw = os.environ.get(env_name)
+    if not raw or not raw.strip():
+        return []
     try:
-        comments = json.loads(os.environ.get("COMMENTS_JSON") or "[]")
+        parsed = json.loads(raw)
     except (ValueError, TypeError):
-        # The caller validated this JSON already; if it is broken here, say so loudly on
-        # stderr and emit no candidate. Silence on stdout means "no override".
-        print("approval-override: COMMENTS_JSON is not valid JSON", file=sys.stderr)
-        return 0
-    if not isinstance(comments, list):
-        print("approval-override: COMMENTS_JSON is not a list", file=sys.stderr)
-        return 0
+        print(
+            "approval-override: %s is not valid JSON — ignoring that source" % label,
+            file=sys.stderr,
+        )
+        return []
+    if isinstance(parsed, list):
+        return parsed
+    # An error object, typically {"message": "token does not have ... scope"}. Say which,
+    # because "no override found" and "could not read the overrides" look identical from
+    # the outside and the first wasted a real debugging session.
+    detail = ""
+    if isinstance(parsed, dict):
+        detail = str(parsed.get("message") or parsed.get("errors") or "")[:200]
+    print(
+        "approval-override: %s is not a list (Gitea returned %s%s) — ignoring that source"
+        % (label, type(parsed).__name__, ": " + detail if detail else ""),
+        file=sys.stderr,
+    )
+    return []
 
-    candidates = []
-    for comment in comments:
-        if not isinstance(comment, dict):
+
+def candidates_from(items, source, directive, head_time):
+    """Yield (when, login, reason, raw_when, source) for every valid override in one source."""
+    found = []
+    for item in items:
+        if not isinstance(item, dict):
             continue
-        login = ((comment.get("user") or {}).get("login") or "").strip()
-        reason = extract_reason(comment.get("body"), directive)
+        login = ((item.get("user") or {}).get("login") or "").strip()
+        reason = extract_reason(item.get("body"), directive)
         if not login or not reason:
             continue
-        created_raw = comment.get("created_at") or comment.get("updated_at") or ""
-        created = parse_ts(created_raw)
-        if created is None:
+        # A PENDING review is an unsubmitted private draft — not an act of anything.
+        state = str(item.get("state") or "").upper()
+        if source == "review" and state == "PENDING":
             print(
-                "approval-override: dropping override by '%s' — unreadable timestamp %r"
-                % (login, created_raw),
+                "approval-override: dropping PENDING (unsubmitted) review by '%s'" % login,
+                file=sys.stderr,
+            )
+            continue
+        raw_when = (
+            item.get("submitted_at") or item.get("created_at") or item.get("updated_at") or ""
+        )
+        when = parse_ts(raw_when)
+        if when is None:
+            print(
+                "approval-override: dropping %s override by '%s' — unreadable timestamp %r"
+                % (source, login, raw_when),
                 file=sys.stderr,
             )
             continue
         # An override must post-date the commit it covers.
-        if head_time is not None and created <= head_time:
+        if head_time is not None and when <= head_time:
             print(
-                "approval-override: dropping STALE override by '%s' (%s) — not newer than "
-                "head commit (%s). Re-comment to override the current commit."
-                % (login, created.isoformat(), head_time.isoformat()),
+                "approval-override: dropping STALE %s override by '%s' (%s) — not newer than "
+                "head commit (%s). Re-post it to override the current commit."
+                % (source, login, when.isoformat(), head_time.isoformat()),
                 file=sys.stderr,
             )
             continue
-        candidates.append((created, login, reason, created_raw))
+        found.append((when, login, reason, raw_when, source))
+    return found
 
-    if not candidates:
+
+def main():
+    directive = os.environ.get("DIRECTIVE", "/approve-override").strip()
+    head_time = parse_ts(os.environ.get("HEAD_TIME", ""))
+
+    found = []
+    found += candidates_from(
+        load_source("COMMENTS_JSON", "COMMENTS_JSON"), "comment", directive, head_time
+    )
+    found += candidates_from(
+        load_source("REVIEWS_JSON", "REVIEWS_JSON"), "review", directive, head_time
+    )
+
+    if not found:
         return 0
 
-    # Latest wins: a later override supersedes an earlier one.
-    created, login, reason, created_raw = max(candidates, key=lambda c: c[0])
+    # Latest wins, across both sources: a later override supersedes an earlier one.
+    when, login, reason, raw_when, source = max(found, key=lambda c: c[0])
     # Keep the reason on one line — this becomes a TSV field.
     reason = " ".join(reason.split())
-    print("%s\t%s\t%s" % (login, created_raw, reason))
+    print("%s\t%s\t%s\t%s" % (login, raw_when, source, reason))
     return 0
 
 

ci/approval-policy.sh

@@ -103,8 +103,15 @@ REVIEWS_JSON="$(api "${GITEA_URL}/api/v1/repos/${GITEA_REPO}/pulls/${PR}/reviews
 # PR conversation comments live under the ISSUES endpoint. `/pulls/{n}/comments` returns review
 # (diff) comments ONLY, so an override posted in the normal comment box would never appear in it.
 # Verified against this Gitea (1.24.3) rather than assumed.
+#
+# This one is NOT in the must-parse loop below, and that is deliberate. /issues/{n}/comments sits
+# behind Gitea's *issue* token scope, which `SETTINGS_API_TOKEN` does not carry (it is minted
+# `[read:repository, read:admin]`) — so it returns an error OBJECT, not an array. Blocking on that
+# turned "CI cannot read your override" into a message that said "you did not post one", and cost a
+# real debugging session on PR #38. It is handled explicitly, and loudly, further down: an
+# unreadable source can only cause a false BLOCK, never a false pass.
 COMMENTS_JSON="$(api "${GITEA_URL}/api/v1/repos/${GITEA_REPO}/issues/${PR}/comments?limit=1000" || true)"
-for v in FILES_JSON PR_JSON REVIEWS_JSON COMMENTS_JSON; do
+for v in FILES_JSON PR_JSON REVIEWS_JSON; do
   jq -e . >/dev/null 2>&1 <<<"${!v}" || {
     err "could not read ${v} from Gitea for PR #${PR} — BLOCKING rather than assuming."
     summary "- approval-policy: **BLOCKED — Gitea unreadable**"
@@ -170,8 +177,23 @@ if [ "$OVERRIDE_ENABLED" = "true" ]; then
     exit 1
   fi
 
-  # Pure, offline, unit-tested selection: which comment, if any, is a live override?
-  OVERRIDE_TSV="$(COMMENTS_JSON="$COMMENTS_JSON" HEAD_TIME="$HEAD_TIME" DIRECTIVE="$DIRECTIVE" \
+  # Is the comments source actually readable? Say so plainly if not — a scope problem and "you
+  # never posted an override" are indistinguishable from the outside, and conflating them is what
+  # made PR #38 look like a code bug.
+  if ! jq -e 'type == "array"' >/dev/null 2>&1 <<<"${COMMENTS_JSON:-}"; then
+    SCOPE_MSG="$(jq -r '.message // empty' <<<"${COMMENTS_JSON:-null}" 2>/dev/null || true)"
+    warn "cannot read PR COMMENTS from Gitea${SCOPE_MSG:+ — ${SCOPE_MSG}}."
+    warn "  /issues/${PR}/comments needs the *issue* token scope; SETTINGS_API_TOKEN is minted"
+    warn "  [read:repository, read:admin] (infra/gitea/set-ci-token.sh). An override posted as an"
+    warn "  ordinary PR COMMENT is therefore invisible to CI — post it as a REVIEW of type"
+    warn "  'Comment' instead, which /pulls/${PR}/reviews exposes under read:repository."
+    summary "- approval-policy: note — PR comments unreadable (token lacks the issue scope); use a **review** to override"
+    COMMENTS_JSON='[]'
+  fi
+
+  # Pure, offline, unit-tested selection: which comment or review, if any, is a live override?
+  OVERRIDE_TSV="$(COMMENTS_JSON="$COMMENTS_JSON" REVIEWS_JSON="$REVIEWS_JSON" \
+    HEAD_TIME="$HEAD_TIME" DIRECTIVE="$DIRECTIVE" \
     python3 "${CI_DIR}/approval-override.py")" || {
       err "ci/approval-override.py failed — BLOCKING rather than assuming there is no override."
       summary "- approval-policy: **BLOCKED — override parser failed**"
@@ -180,7 +202,8 @@ if [ "$OVERRIDE_ENABLED" = "true" ]; then
   if [ -n "$OVERRIDE_TSV" ]; then
     OV_USER="$(cut -f1 <<<"$OVERRIDE_TSV")"
     OV_WHEN="$(cut -f2 <<<"$OVERRIDE_TSV")"
-    OV_WHY="$(cut -f3- <<<"$OVERRIDE_TSV")"
+    OV_SRC="$(cut -f3 <<<"$OVERRIDE_TSV")"
+    OV_WHY="$(cut -f4- <<<"$OVERRIDE_TSV")"
 
     # AUTHORITY IS MEASURED LIVE, never inferred from the comment or from a name in git.
     PERM_JSON="$(api "${GITEA_URL}/api/v1/repos/${GITEA_REPO}/collaborators/${OV_USER}/permission" || true)"
@@ -214,12 +237,13 @@ print("yes" if (ok_perm and ok_list) else "no")
       else
         warn "ADMIN OVERRIDE by '${OV_USER}' (permission '${OV_PERM}'); author is '${AUTHOR}'."
       fi
+      warn "  via:    PR ${OV_SRC}"
       warn "  when:   ${OV_WHEN}  (head commit ${HEAD_SHA:0:8}, ${HEAD_TIME})"
       warn "  reason: ${OV_WHY}"
       warn "  review waived on: $(printf '%s ' $SENSITIVE)"
       ok "sensitive paths cleared by administrator override — this stage does not block."
       SELFNOTE=""; [ "$OV_USER" = "$AUTHOR" ] && SELFNOTE=", **self-waived as author**"
-      summary "- approval-policy: **OVERRIDDEN by \`${OV_USER}\`** (permission \`${OV_PERM}\`${SELFNOTE})"
+      summary "- approval-policy: **OVERRIDDEN by \`${OV_USER}\`** (permission \`${OV_PERM}\`, via PR ${OV_SRC}${SELFNOTE})"
       summary "  - reason: ${OV_WHY}"
       summary "  - review waived on: $(printf '\`%s\` ' $SENSITIVE)"
       exit 0
@@ -239,10 +263,12 @@ err "  honestly approve for itself. Get a human review, or move the change out o
 printf '    %s\n' $SENSITIVE >&2
 err "  The list lives in infra/gitea/approval-policy.json, with a reason per entry."
 if [ "$OVERRIDE_ENABLED" = "true" ]; then
-  err "  Or, if you hold admin/owner on this repository, comment on the PR:"
+  err "  Or, if you hold admin/owner on this repository, post this on the PR:"
   err "      ${DIRECTIVE} <reason>"
-  err "  The reason is mandatory, the directive must START a line, and the comment must be"
-  err "  NEWER than head commit ${HEAD_SHA:0:8} — push again and you must override again."
+  err "  as a REVIEW of type 'Comment' (not the plain comment box — CI's token cannot read"
+  err "  /issues/${PR}/comments without the issue scope; see infra/gitea/set-ci-token.sh)."
+  err "  The reason is mandatory, the directive must START a line, and it must be NEWER than"
+  err "  head commit ${HEAD_SHA:0:8} — push again and you must override again."
 fi
 summary "- approval-policy: **BLOCKED — needs a non-author approval, or an admin \`${DIRECTIVE}\` comment**"
 exit 1

ci/tests/approval-override.test.sh

@@ -26,7 +26,13 @@ BEFORE="2026-10-01T11:30:00Z"
 
 # run <comments-json> -> stdout of the parser (stderr is diagnostic only)
 run() {
-  COMMENTS_JSON="$1" HEAD_TIME="${2:-$HEAD_TIME}" DIRECTIVE="${3:-/approve-override}" \
+  COMMENTS_JSON="$1" REVIEWS_JSON="" HEAD_TIME="${2:-$HEAD_TIME}" DIRECTIVE="${3:-/approve-override}" \
+    python3 "$SUT" 2>/dev/null
+}
+
+# run_rev <reviews-json> — the same, but through the REVIEWS source.
+run_rev() {
+  COMMENTS_JSON="" REVIEWS_JSON="$1" HEAD_TIME="${2:-$HEAD_TIME}" DIRECTIVE="${3:-/approve-override}" \
     python3 "$SUT" 2>/dev/null
 }
 
@@ -54,10 +60,24 @@ expect_user() {
 expect_reason() {
   local label="$1" json="$2" want="$3" out got
   out="$(run "$json")"
-  got="$(cut -f3- <<<"$out")"
+  got="$(cut -f4- <<<"$out")"
   if [ "$got" = "$want" ]; then ok "$label"; else bad "$label (wanted '${want}', got '${got}')"; fi
 }
 
+# check <label> <actual> <wanted>
+check() {
+  if [ "$2" = "$3" ]; then ok "$1"; else bad "$1 (wanted '${3}', got '${2}')"; fi
+}
+
+# review <login> <submitted_at> <state> <body>
+review() {
+  python3 -c '
+import json, sys
+print(json.dumps([{"user": {"login": sys.argv[1]}, "submitted_at": sys.argv[2],
+                   "state": sys.argv[3], "body": sys.argv[4]}]))
+' "$1" "$2" "$3" "$4"
+}
+
 echo "== ci/approval-override.py"
 
 # --- the happy path -------------------------------------------------------------------
@@ -141,5 +161,72 @@ else
   bad "with no HEAD_TIME the candidate should still be returned (got '${out}')"
 fi
 
+# --- the REVIEWS source ---------------------------------------------------------------
+# Load-bearing, not redundant. Measured on PR #38: SETTINGS_API_TOKEN is minted
+# [read:repository, read:admin], /issues/{n}/comments needs the ISSUE scope, so a well-formed
+# override in the comment box came back as an error object and was invisible. /pulls/{n}/reviews
+# IS readable with that token, so a review body is the route that works today.
+check "a review body carries an override" \
+  "$(cut -f1 <<<"$(run_rev "$(review jakman85 "$AFTER" COMMENT '/approve-override via a review')")")" \
+  jakman85
+check "the source is reported as 'review'" \
+  "$(cut -f3 <<<"$(run_rev "$(review jakman85 "$AFTER" COMMENT '/approve-override via a review')")")" \
+  review
+check "the source is reported as 'comment' for a comment" \
+  "$(cut -f3 <<<"$(run "$(comment jakman85 "$AFTER" '/approve-override via a comment')")")" \
+  comment
+
+out="$(run_rev "$(review jakman85 "$BEFORE" COMMENT '/approve-override stale review')")"
+check "a stale review override is dropped too" "${out:-<none>}" "<none>"
+
+out="$(run_rev "$(review jakman85 "$AFTER" PENDING '/approve-override unsubmitted draft')")"
+check "a PENDING (unsubmitted) review is NOT an act of anything" "${out:-<none>}" "<none>"
+
+check "an APPROVED review carrying the directive still counts as an override" \
+  "$(cut -f1 <<<"$(run_rev "$(review jakman85 "$AFTER" APPROVED '/approve-override belt and braces')")")" \
+  jakman85
+
+out="$(run_rev "$(review jakman85 "$AFTER" COMMENT 'ordinary review prose, no directive')")"
+check "an ordinary review body is not an override" "${out:-<none>}" "<none>"
+
+# --- an unreadable source degrades to 'no candidates', never to a pass ----------------
+# The real-world shape: Gitea answers with {"message": "token does not have ... scope"}.
+ERR_OBJ='{"message":"token does not have at least one of required scope(s): [read:issue]"}'
+out="$(COMMENTS_JSON="$ERR_OBJ" REVIEWS_JSON="" HEAD_TIME="$HEAD_TIME" \
+       DIRECTIVE=/approve-override python3 "$SUT" 2>/dev/null)"
+check "an error OBJECT from the comments API yields no override" "${out:-<none>}" "<none>"
+
+out="$(COMMENTS_JSON="$ERR_OBJ" \
+       REVIEWS_JSON="$(review jakman85 "$AFTER" COMMENT '/approve-override reviews still work')" \
+       HEAD_TIME="$HEAD_TIME" DIRECTIVE=/approve-override python3 "$SUT" 2>/dev/null)"
+check "an unreadable COMMENTS source does not suppress a valid REVIEW override" \
+  "$(cut -f1 <<<"$out")" jakman85
+
+# and it must SAY so, or a scope problem reads as 'you never posted one' (it did, on PR #38)
+errout="$(COMMENTS_JSON="$ERR_OBJ" REVIEWS_JSON="" HEAD_TIME="$HEAD_TIME" \
+          DIRECTIVE=/approve-override python3 "$SUT" 2>&1 >/dev/null)"
+case "$errout" in
+  *"not a list"*read:issue*) ok "the diagnostic names the scope Gitea complained about" ;;
+  *) bad "the diagnostic should quote Gitea's message (got: ${errout})" ;;
+esac
+
+# --- latest wins ACROSS the two sources ----------------------------------------------
+out="$(COMMENTS_JSON="$(comment early "2026-10-01T12:10:00Z" '/approve-override from a comment')" \
+       REVIEWS_JSON="$(review later "2026-10-01T12:50:00Z" COMMENT '/approve-override from a review')" \
+       HEAD_TIME="$HEAD_TIME" DIRECTIVE=/approve-override python3 "$SUT" 2>/dev/null)"
+check "the latest override wins across both sources (review newer)" "$(cut -f1 <<<"$out")" later
+check "and its source is labelled" "$(cut -f3 <<<"$out")" review
+
+out="$(COMMENTS_JSON="$(comment later "2026-10-01T12:50:00Z" '/approve-override from a comment')" \
+       REVIEWS_JSON="$(review early "2026-10-01T12:10:00Z" COMMENT '/approve-override from a review')" \
+       HEAD_TIME="$HEAD_TIME" DIRECTIVE=/approve-override python3 "$SUT" 2>/dev/null)"
+check "the latest override wins across both sources (comment newer)" "$(cut -f1 <<<"$out")" later
+check "and that source is labelled too" "$(cut -f3 <<<"$out")" comment
+
+# --- both sources absent entirely -----------------------------------------------------
+out="$(COMMENTS_JSON="" REVIEWS_JSON="" HEAD_TIME="$HEAD_TIME" \
+       DIRECTIVE=/approve-override python3 "$SUT" 2>/dev/null)"
+check "no sources at all yields no override, and no crash" "${out:-<none>}" "<none>"
+
 printf '\n  %d passed, %d failed\n' "$PASS" "$FAIL"
 [ "$FAIL" -eq 0 ] || exit 1

decisions/2026-10-01-admin-approval-override.md

@@ -87,6 +87,43 @@ Also updated: `CLAUDE.md` §1 and the §2 enforcement table (the "approval requi
 explicitly ⬜ with the reason, rather than a stale ✅), and `infra/gitea/README.md` gains §6 and
 marks its historical step 4 as reversed — do not re-apply.
 
+**Second pass, 2026-10-02 — the override did not work the first time, and why.** The operator ran
+the live PATCH (`required_approvals: 0` confirmed live, with `block_admin_merge_override` and
+`enable_status_check` still `true`), merged PR #35, and posted `/approve-override Need to ensure
+approval override work as expected` on PR #38. The gate re-ran (run 203) and **still blocked.**
+
+The comment was not at fault: posted by `jakman85`, directive at the start of the line, reason
+present, and 29 minutes **newer** than head commit `616a497`, so it cleared the staleness rule.
+What failed was that **CI could not read it.** Run 203's log:
+
+    approval-override: COMMENTS_JSON is not a list
+
+`SETTINGS_API_TOKEN` is minted `["read:repository", "read:admin"]` by
+`infra/gitea/set-ci-token.sh`, and Gitea puts `/issues/{n}/comments` behind the **issue** scope. So
+Gitea returned an error *object*, `jq -e .` accepted it as valid JSON, and the stage fell through
+to "no approving review" — **a permission failure wearing the costume of a missing override.**
+`/pulls/{n}/files` and `/pulls/{n}/reviews` are under `read:repository`, which is exactly why every
+other part of the same stage worked and this one did not.
+
+Three fixes, and the first is the one that mattered most:
+
+1. **The diagnosis is no longer misleading.** `COMMENTS_JSON` is out of the must-parse-or-block
+   loop and is explicitly checked for being an *array*; when it is not, the stage prints Gitea's
+   own `.message`, names the missing scope, and says where to post the override instead. An
+   unreadable source can only cause a false BLOCK, never a false pass, so degrading it to a loud
+   warning is safe — and blocking on it was never the honest behaviour.
+2. **The override is accepted from a PR REVIEW body as well as a comment**, so the hatch is not
+   hostage to one API scope. A review of type "Comment" works on the token CI has *today*. The
+   gate names which source it used. `PENDING` (unsubmitted, author-only draft) reviews are dropped.
+3. **`set-ci-token.sh` now requests `read:issue`**, which makes the ordinary comment box work —
+   the thing anybody reaches for first. It takes effect only on a **re-run**: an existing token's
+   scopes cannot be widened in place.
+
+`ci/tests/approval-override.test.sh` grows from 23 to **38 assertions**, covering the reviews
+source, `PENDING` reviews, an error *object* from the comments API, "an unreadable comments source
+must not suppress a valid review override", latest-wins across both sources, and that the
+diagnostic actually quotes Gitea's message.
+
 **One adjacent fix, deliberately in scope: `ci/tests/gate-decision.test.sh` was already broken.**
 It hand-maintains a list of stub stage scripts that "must name EVERY stage `gate.sh` runs", and it
 did not name `approval-policy` — added to `gate.sh` by PR #17 and never added here. `run_stage`
@@ -130,8 +167,30 @@ missing from its test. `make -C ci test` goes from **FAILED to all suites passed
   **FAIL, 15 failed / 35 passed**. After deriving the stub list from `gate.sh`: **PASS, 50
   assertions**.
 - **`make -C ci test` in the pinned toolbox: `ci/tests: all suites passed`, rc 0** — approval-override
-  23, gate-decision 50, touched-requirements-base 31, test-attribution 15, touched-requirements 26,
+  **38**, gate-decision 50, touched-requirements-base 31, test-attribution 15, touched-requirements 26,
   decisions-log pass. It was rc 2 (`ci/tests: FAILED`) before the stub-list fix.
+- **The live flip worked, and the drift detector proved it.** Run 202 (before): `gitea-settings:
+  FAIL`, `required_approvals: DECLARED 0 but LIVE is 1`. Run 203 (after the operator ran the
+  PATCH): `gitea-settings: pass`, with `block_admin_merge_override = true` among the keys it
+  checked. So the narrow change held — the approval count moved and the gate's teeth did not.
+- **The first override attempt failed for a measured reason, not a guessed one.** Run 203 log:
+  `approval-override: COMMENTS_JSON is not a list`. Token scopes read from `set-ci-token.sh`:
+  `[read:repository, read:admin]`. The same run successfully read `/pulls/38` and
+  `/pulls/38/files` (author and sensitive paths both resolved) and got past the reviews
+  validation, which is how I know `/pulls/{n}/reviews` IS readable with that token — from
+  behaviour, not from documentation.
+- **The comment itself was valid.** `created_at` 2026-10-02T05:31:24Z vs head commit `616a497`
+  committer date 2026-10-02T00:02:20-05:00 → the comment is 29m04s newer, so it passed the
+  staleness rule. Ruling the comment out is what left the token scope as the only candidate.
+- **`?limit=1000` is not the culprit.** Queried `/issues/38/comments` with `limit=1000`, `limit=50`
+  and no limit using my own credentials: `type=array` in all three. So the difference is the
+  credential, not the query.
+- **The root cause is confirmed by Gitea, in its own words.** Run 206 (the fix in place):
+  `[warn] cannot read PR COMMENTS from Gitea — token does not have at least one of required
+  scope(s), required=[read:issue], token scope=read:admin,read:repository.` followed by the
+  instruction to post the override as a review. That is the diagnosis the first attempt should
+  have produced, and `gitea-settings: pass` in the same run. The stage still ends `FAIL`, correctly
+  — there is no valid override on the PR yet.
 - **Toolbox merge gate** (`./infra/devcontainer/dev.sh run bash -c './ci/gate.sh'`), run on the
   rebased branch: **rc 3, `MERGE GATE: UNDETERMINED`**. Green stages: spec-immutability,
   decisions-log, lint, l0 (23 offline cases, 0 failures), render-golden including the new
@@ -142,20 +201,32 @@ missing from its test. `make -C ci test` goes from **FAILED to all suites passed
 
 ## What I did NOT verify
 
-- **The live Gitea rule still says `required_approvals: 1`. I did not change it.** Mutating live
-  platform settings is an operator action; `infra/gitea/allow-admin-self-merge.sh` is written,
-  syntax-checked, and **unrun**. The declaration and the live rule must move together.
-  *Now measured, not predicted:* PR #38's CI run (run 202, job 0) fails at **1m44s** with
-  `required_approvals: DECLARED 0 but LIVE is 1` → `gitea-settings: FAIL`. Correct behaviour, and
-  the PR stays red until the script is run.
-- **The override has never been ACCEPTED by a real run** — only offered. Measured in the same CI
-  log: the stage reached `approval-policy: FAIL` on the sensitive paths and printed the *new*
-  code's guidance, `Or, if you hold admin/owner on this repository, comment on the PR:
-  /approve-override <reason> ... NEWER than head commit 7b9f733c`. So the new stage **is** what
-  runs on this PR (self-bootstrapping confirmed by measurement, not by reasoning), and the
-  authorising branch — comment parse → live permission lookup → exit 0 — is still **unexercised**.
-  Posting the comment on PR #38 is its first real test. If it does not work, the recovery is to
-  PATCH `required_approvals` and read run 202's successor log.
+- **The override has still never been ACCEPTED by a real run.** This is the second attempt at
+  this bullet, which is itself the point: the first pass called the hatch unverified, and the
+  first real test found a defect that no amount of local testing would have (an API scope CI has
+  and I did not). What is now measured is that the parse → *reject* path works end to end and
+  diagnoses itself. The **accepting** branch — directive found → live permission lookup → exit 0 —
+  has never executed. Posting the override as a **review** on PR #38 is its first real test, and
+  I would not be surprised by a third round.
+- **`read:issue` is the right scope name — Gitea said so itself, so this is no longer a guess.**
+  Run 206 printed Gitea's own message: `token does not have at least one of required scope(s),
+  required=[read:issue], token scope=read:admin,read:repository`. That both confirms the root
+  cause and names the string, which matters because this repo has been burned by a token *name*
+  that could not exist (`GITEA_SETTINGS_TOKEN`). What is **still** unverified is that the token
+  *mint* accepts it — `POST /users/{u}/tokens` with that scope has not been run. The review route
+  does not depend on it.
+- **I did not verify that Gitea lets a PR's own author submit a `COMMENT`-type review.** Gitea
+  blocks author self-*approval*; "Comment" is expected to be allowed, and that expectation is now
+  load-bearing for the recommended route. It is one click to find out, and I deliberately did not
+  test it by posting an override myself: doing so as `gitea-admin` is precisely the agent
+  self-override that `CLAUDE.md` now forbids.
+- **The whole re-run mechanism is manual.** `gate.yml` triggers on `pull_request` and `push: main`
+  only — there is no `issue_comment` trigger, so posting an override does **not** re-run the gate.
+  Re-run the job from the Actions UI, or close and reopen the PR (which fires `pull_request` and
+  leaves the head SHA alone). **Do not push an empty commit to re-trigger it:** that moves the head
+  commit and makes the override stale by the rule above, so it would have to be posted again. A
+  comment trigger was considered and not built — it would need to check out PR head code while the
+  job holds `SETTINGS_API_TOKEN`, which is the classic pwn-request shape and not worth it here.
 - **I have not seen the gate still REFUSE a merge** now that approvals are 0. The claim that
   `block_admin_merge_override: true` keeps a red gate unmergeable rests on Gitea's documented
   behaviour and on the 2026-09-29 session, **not** on a provoked refusal in this one. That probe

infra/gitea/README.md

@@ -161,7 +161,18 @@ a *green* one no longer needs a signature that cannot exist.
 **Security-relevant changes are still reviewed** — by `ci/approval-policy.sh` against
 `approval-policy.json` `sensitive_paths`, not by this field. An administrator waives that review
 only by posting `/approve-override <reason>` on the PR: reason mandatory, permission re-checked
-live, invalidated by a new commit, and recorded by account in the gate summary. Note that the
+live, invalidated by a new commit, and recorded by account in the gate summary.
+
+> **Post the override as a PR *review* (type "Comment"), not in the plain comment box** — until
+> the CI token is re-minted. `SETTINGS_API_TOKEN` is `[read:repository, read:admin]`, and
+> `/issues/{n}/comments` needs Gitea's *issue* scope, so Gitea answers with an error **object**
+> instead of an array and the override is invisible. Measured on PR #38 (2026-10-02): a correct,
+> fresh, well-formed override in the comment box produced `approval-policy: FAIL` reading as "no
+> approving review" — a permission failure disguised as a missing one. `/pulls/{n}/reviews` is
+> under `read:repository` and worked in the same run. The stage now reads **both** sources, names
+> which one it used, and says plainly when the comments API is unreadable. `set-ci-token.sh`
+> requests `read:issue` as of 2026-10-02, so **re-run it** and the comment box works too — token
+> scopes cannot be widened in place. Note that the
 **agent account `gitea-admin` also reports permission `owner`**, so it can clear its own PRs that
 way; that is an accepted consequence of authorising by permission alone, and the route to
 narrowing it (an `override_admins` allowlist, already honoured by the code) is written down in

infra/gitea/approval-policy.json

@@ -32,7 +32,8 @@
     "requires_reason": true,
     "authorized_permissions": ["admin", "owner"],
     "invalidated_by_new_commits": true,
-    "_how": "Comment on the PR with the directive at the START of a line, followed by a reason: '/approve-override <why>'. ci/approval-policy.sh resolves the commenter's LIVE repo permission via /collaborators/{login}/permission and accepts the override only if it is in authorized_permissions. The overrider, the timestamp and the reason are printed in the gate log and the job summary.",
+    "_how": "Post the directive at the START of a line, followed by a reason: '/approve-override <why>'. ci/approval-policy.sh resolves the poster's LIVE repo permission via /collaborators/{login}/permission and accepts the override only if it is in authorized_permissions. The overrider, the source, the timestamp and the reason are printed in the gate log and the job summary.",
+    "_where_to_post_it": "EITHER a PR REVIEW body (type 'Comment') OR the ordinary PR comment box. Prefer the REVIEW: measured 2026-10-02 on PR #38, a well-formed override in the comment box was INVISIBLE to CI, because /issues/{n}/comments sits behind Gitea's *issue* token scope and SETTINGS_API_TOKEN is minted [read:repository, read:admin]. Gitea returned an error object rather than an array, and the stage reported 'no approving review' -- a permission problem wearing the costume of a missing override. /pulls/{n}/reviews is under read:repository and was readable in the same run, so a review body is the route that works on today's token. infra/gitea/set-ci-token.sh now also requests read:issue, which makes the comment box work -- but only after that script is RE-RUN, since an existing token's scopes cannot be widened in place. The stage accepts both sources and names which one it used, so neither route is load-bearing alone.",
     "_self_override_is_allowed": "The author may override their own PR if they hold an authorized permission. That is the entire point -- with one human there is no one else -- but it means the 'a change to the gate cannot be gated by the gate' protection is, for an administrator, advisory rather than structural. It is traded for an auditable record: the waiver is an explicit act, attributed, with a stated reason, in the PR's comment history and the gate output.",
     "_known_consequence_agent_accounts": "ACCEPTED, EYES OPEN (operator decision, 2026-10-01). Authorisation is by live permission ALONE, with no allowlist of human accounts. The agent account `gitea-admin` reports permission `owner` on this repo (measured 2026-10-01), so an AGENT can clear the sensitive-path review on its own PR by posting the directive. Agents author most PRs here, so this is the broad case, not the edge case. To narrow it later without changing any logic, add an `override_admins` allowlist here and require membership in addition to the permission check -- ci/approval-policy.sh reads both from this file.",
     "_staleness": "An override is dropped unless its comment is NEWER than the PR head commit, mirroring Gitea's own dismiss_stale_approvals. An override earned at commit A therefore does not silently cover commit B; push again and you must override again."

infra/gitea/set-ci-token.sh

@@ -5,9 +5,23 @@
 # The token value is NEVER printed. It goes from the token API into the secrets API and
 # nowhere else -- not to stdout, not to a file, not into an agent transcript.
 #
-# Scope: `read:repository` + `read:admin` are what the check needs (the rule object, and the
-# runner list). Gitea token scopes are coarse; grant the least that works on your version and
-# confirm the check goes green rather than assuming the scope name.
+# Scope: `read:repository` + `read:admin` are what ci/gitea-settings.sh needs (the rule object,
+# and the runner list). `read:issue` is for ci/approval-policy.sh, and it was MISSING — see below.
+# Gitea token scopes are coarse; grant the least that works on your version and confirm the check
+# goes green rather than assuming the scope name.
+#
+# WHY read:issue IS HERE (added 2026-10-02, measured on PR #38). ci/approval-policy.sh reads the
+# PR's comments to find an admin `/approve-override`. /issues/{n}/comments sits behind the *issue*
+# scope, which this script did not request — so Gitea answered with an error OBJECT instead of an
+# array, and a perfectly well-formed override posted in the PR comment box was invisible to CI.
+# The failure did not look like a permission problem from the outside; it looked like the override
+# had not been posted. `/pulls/{n}/files` and `/pulls/{n}/reviews` are under read:repository, which
+# is why every other part of the same stage worked and this one did not.
+#
+# The stage now accepts an override from a REVIEW body as well, so it still functions on a token
+# WITHOUT read:issue. This scope is what makes the ordinary comment box work too — the thing
+# anybody would reach for first. **Re-run this script to pick it up; an existing token's scopes
+# cannot be widened in place.**
 set -euo pipefail
 HOST=gitea.home.keithjackson.dev; OWNER=Home-Network; REPO=home-network-k3s-impl
 # NOT GITEA_* — Gitea reserves that prefix for secret names and returns HTTP 400
@@ -21,7 +35,7 @@ basic() { curl -sS --config <(printf 'user = "%s:%s"\n' "$U" "$P") "$@"; }
 
 echo "==> minting token '${NAME}' as ${U}"
 TOKEN="$(basic -X POST -H 'Content-Type: application/json' \
-  -d "{\"name\":\"${NAME}\",\"scopes\":[\"read:repository\",\"read:admin\"]}" \
+  -d "{\"name\":\"${NAME}\",\"scopes\":[\"read:repository\",\"read:admin\",\"read:issue\"]}" \
   "https://${HOST}/api/v1/users/${U}/tokens" | jq -r '.sha1 // empty')"
 [ -n "$TOKEN" ] || { echo "token creation failed (check scopes for your Gitea version)" >&2; exit 1; }
 echo "==> got a ${#TOKEN}-character token (value not shown)"