forgedock 1.8.3 → 1.9.0

package/scripts/lint-build-validate-files.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Lint: every work-on:build:validate Skill( invocation in build.md must carry --files,
+# and the B6.5 repair section must contain an explicit one (forge#3254).
+# Usage: bash scripts/lint-build-validate-files.sh [path/to/build.md]
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SPEC="${1:-$HERE/../commands/work-on/build.md}"
+[ -f "$SPEC" ] || { echo "lint-build-validate-files: spec not found: $SPEC" >&2; exit 2; }
+rc=0
+calls=$(grep -n 'Skill(skill=.*work-on:build:validate' "$SPEC" || true)
+if [ -z "$calls" ]; then
+  echo "FAIL: no work-on:build:validate Skill( invocation found in $SPEC" >&2
+  exit 1
+fi
+bad=$(printf '%s\n' "$calls" | grep -vF -- '--files' || true)
+if [ -n "$bad" ]; then
+  printf '%s\n' "$bad" | while IFS= read -r l; do
+    echo "FAIL: $SPEC:${l%%:*}: validate invocation lacks --files" >&2
+  done
+  rc=1
+fi
+if ! awk '/Phase B6\.5/{f=1} f' "$SPEC" | grep 'Skill(skill=.*work-on:build:validate' | grep -qF -- '--files'; then
+  echo "FAIL: $SPEC: B6.5 repair section has no explicit validate invocation carrying --files" >&2
+  rc=1
+fi
+[ "$rc" -eq 0 ] && echo "OK: all validate invocations carry --files"
+exit "$rc"

package/scripts/lint-build-validate-files.test.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Fixtures for lint-build-validate-files.sh (forge#3254). Run: bash scripts/lint-build-validate-files.test.sh
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+LINT="$HERE/lint-build-validate-files.sh"
+T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT
+PASS=0; FAILN=0
+check() { # name want_rc file
+  bash "$LINT" "$3" >"$T/out" 2>&1; rc=$?
+  if [ "$rc" -eq "$2" ]; then PASS=$((PASS+1)); else FAILN=$((FAILN+1)); echo "FAIL: $1 (rc=$rc want $2)"; cat "$T/out"; fi
+}
+V='Skill(skill="{FORGE_SKILL_PREFIX}work-on:build:validate", args="{NUMBER} --worktree {W}'
+printf '## Phase B6\n%s --files \\"{CHANGED_FILES}\\"")\n## Phase B6.5\n%s --files \\"{CHANGED_FILES}\\"")\n' "$V" "$V" > "$T/ok.md"
+check "all carry --files" 0 "$T/ok.md"
+printf '## Phase B6\n%s --files \\"x\\"")\n## Phase B6.5\n%s")\n' "$V" "$V" > "$T/bad1.md"
+check "one invocation lacks --files" 1 "$T/bad1.md"
+printf '## Phase B6\n%s --files \\"x\\"")\n## Phase B6.5\nfollowed by work-on:build:validate with the same args\n' "$V" > "$T/bad2.md"
+check "B6.5 has no explicit invocation" 1 "$T/bad2.md"
+printf 'nothing here\n' > "$T/bad3.md"
+check "no invocations at all" 1 "$T/bad3.md"
+check "real build.md" 0 "$HERE/../commands/work-on/build.md"
+echo "passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/lint-dispatch-prompt.test.sh

@@ -229,7 +229,8 @@ check "mid-line CR not stripped" 1 "$T/p25"
 # 10. Spec snippet enforcement (forge#3070): extract the lint gate from the spec and run it in a loop.
 # Gate = from the bootstrap marker to the end of its fenced code block (not a hard-coded count of
 # top-level fi lines, which breaks whenever the bootstrap gains or loses a conditional).
-awk '/^# FORGE_ROOT bootstrap/{f=1} f&&/^```/{exit} f{print}' "$SPEC" > "$T/gate"
+# Several spec blocks carry the bootstrap marker (e.g. the recovery-claim gate, forge#3172); pick the one holding the lint gate.
+awk '/^# FORGE_ROOT bootstrap/{f=1;buf=""} f&&/^```/{if(buf ~ /LINT_REFUSED_ISSUES/){printf "%s",buf;exit} f=0} f{buf=buf $0 "\n"}' "$SPEC" > "$T/gate"
 [ -s "$T/gate" ] || { FAILN=$((FAILN+1)); echo "FAIL: could not extract spec lint gate"; }
 gate_refused() { # prompt-file home -> prints refusal entries or LAUNCHED
   ( LINT_REFUSED_ISSUES=(); RENDERED_PROMPT="$(cat "$1")"; FORGEDOCK_HOME="$2"; unset FORGE_HOME; reset_vals

package/scripts/recovery-claim-live.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# recovery-claim-live.sh — is an issue currently claimed by a /recover-orphans sweep?
+#
+# Single source of truth for the dispatcher-side check of FORGE:RECOVERY_CLAIM, used by
+# /work-on Phase 0B and /orchestrate Phase 4 so a dispatcher never re-enters an issue a sweep is
+# resuming. Same semantics as `claim_orphan` in commands/recover-orphans.md: a claim is LIVE when it
+# is an unreleased `<!-- FORGE:RECOVERY_CLAIM -->` comment, its `updated_at` is within
+# RECOVERY_CLAIM_TTL_MIN (default 30) minutes, and no `FORGE:RECOVERY_CLAIM_RELEASED` comment names
+# its sweep id. FORGE:HEARTBEAT is deliberately NOT counted: a dispatcher must not defer to another
+# dispatcher's heartbeat (that is the lease/claims-board job).
+#
+# Usage:
+#   recovery-claim-live.sh <issue> -R <owner/repo> [--exempt-sweep <sweep-id>]
+#
+#   --exempt-sweep  Ignore the claim held by this sweep id (the calling sweep's own claim), so the
+#                   holder's inline /work-on is not blocked by its own claim. A claim with no
+#                   parsable sweep id is never exempt (and `unknown` is rejected as an exemption id).
+#
+# Output (stdout): CLAIM: LIVE <sweep-id> | CLAIM: FREE | CLAIM: ERROR
+# Exit codes: 0 free, 1 live, 2 error (unreadable comments or usage; fails closed — callers must
+# treat 2 like "live" and defer, never like "free").
+#
+# Trust note: any commenter's claim marker counts (same as claim_orphan). A spoofed claim can only
+# defer an issue for RECOVERY_CLAIM_TTL_MIN unless it is refreshed.
+# END-HELP (`-h` prints the header up to this line; keep it last)
+
+set -uo pipefail
+
+ISSUE=""; REPO=""; EXEMPT=""
+err() { echo "CLAIM: ERROR"; echo "$1" >&2; exit 2; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -R|--repo)
+      [ $# -ge 2 ] && [ -n "${2:-}" ] || err "usage error: $1 needs a value"
+      REPO="$2"; shift 2 ;;
+    --exempt-sweep)
+      [ $# -ge 2 ] && [ -n "${2:-}" ] || err "usage error: $1 needs a value"
+      [ "$2" != "unknown" ] || err "usage error: --exempt-sweep 'unknown' is the no-sweep-id sentinel and cannot exempt a claim"
+      EXEMPT="$2"; shift 2 ;;
+    -h|--help) awk 'NR >= 5 { if (/^# END-HELP/) exit; print }' "$0"; exit 0 ;;
+    *)
+      if [ -z "$ISSUE" ] && [[ "$1" =~ ^[0-9]+$ ]]; then ISSUE="$1"; shift
+      else err "usage error: unexpected argument '$1'"; fi ;;
+  esac
+done
+[ -n "$ISSUE" ] && [ -n "$REPO" ] || err "usage: recovery-claim-live.sh <issue> -R <owner/repo> [--exempt-sweep <id>]"
+
+TTL="${RECOVERY_CLAIM_TTL_MIN:-30}"
+[[ "$TTL" =~ ^[0-9]+$ ]] || TTL=30
+CUTOFF=$(( $(date -u +%s) - TTL * 60 ))
+
+# pipefail: a gh failure (rate limit, 403) must not look like "no comments".
+COMMENTS=$(gh api --paginate "repos/${REPO}/issues/${ISSUE}/comments" 2>/dev/null | jq -s 'add // []') \
+  || err "could not read comments for #${ISSUE}"
+
+LIVE=$(echo "$COMMENTS" | jq -r --argjson cutoff "$CUTOFF" --arg exempt "$EXEMPT" '
+  def sweepid: ((.body | capture("Sweep: (?<id>[^ \n*]+)")?) // {id: "unknown"}).id;
+  # "unknown" is the no-id sentinel, never a matchable id: an unparsable release frees nothing (fail closed).
+  ([.[] | select(.body | contains("FORGE:RECOVERY_CLAIM_RELEASED")) | sweepid] | map(select(. != "unknown"))) as $rel
+  | [ .[] | select(.body | contains("<!-- FORGE:RECOVERY_CLAIM -->"))
+          | select((.body | contains("FORGE:RECOVERY_CLAIM_RELEASED")) | not)
+          | select(((.updated_at // "") | fromdateiso8601? // 9999999999) >= $cutoff)
+          | select(sweepid as $sid | ($rel | index($sid)) == null)
+          | select($exempt == "" or sweepid == "unknown" or sweepid != $exempt)
+          | sweepid ] | first // empty') \
+  || err "could not evaluate recovery claims for #${ISSUE}"
+
+if [ -n "$LIVE" ]; then echo "CLAIM: LIVE ${LIVE}"; exit 1; fi
+echo "CLAIM: FREE"; exit 0

package/scripts/recovery-claim-live.test.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# recovery-claim-live.test.sh — tests for scripts/recovery-claim-live.sh
+# No network: `gh` is mocked on PATH; MOCK_GH_JSON names a fixture holding the JSON array
+# `gh api .../comments` would return. MOCK_GH_FAIL=1 simulates an outage.
+#
+# Usage: bash scripts/recovery-claim-live.test.sh
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHECK="$SCRIPT_DIR/recovery-claim-live.sh"
+TMP_BIN=$(mktemp -d); TMP_FX=$(mktemp -d)
+trap 'rm -rf "$TMP_BIN" "$TMP_FX"' EXIT
+
+cat > "$TMP_BIN/gh" <<'MOCK'
+#!/usr/bin/env bash
+if [ "${MOCK_GH_FAIL:-}" = "1" ]; then echo "mock gh: outage" >&2; exit 1; fi
+cat "$MOCK_GH_JSON"
+MOCK
+chmod +x "$TMP_BIN/gh"
+export PATH="$TMP_BIN:$PATH"
+
+PASS=0; FAILN=0
+ok()  { PASS=$((PASS+1)); echo "ok   - $1"; }
+bad() { FAILN=$((FAILN+1)); echo "FAIL - $1"; }
+
+now_iso()  { date -u +%Y-%m-%dT%H:%M:%SZ; }
+old_iso()  { date -u -d '2 hours ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-2H +%Y-%m-%dT%H:%M:%SZ; }
+
+# fx <name> <json-array>
+fx() { echo "$2" > "$TMP_FX/$1.json"; echo "$TMP_FX/$1.json"; }
+claim()   { jq -cn --arg id "$1" --arg t "$2" '{body:("<!-- FORGE:RECOVERY_CLAIM -->\n**Sweep: "+$id+"**\nHolder: /recover-orphans"), updated_at:$t}'; }
+release() { jq -cn --arg id "$1" --arg t "$2" '{body:("<!-- FORGE:RECOVERY_CLAIM_RELEASED -->\n**Sweep: "+$id+"**\nReleased"), updated_at:$t}'; }
+
+run() { local f="$1"; shift; OUT=$(MOCK_GH_JSON="$f" bash "$CHECK" 7 -R o/r "$@" 2>/dev/null); RC=$?; }
+expect() { # name rc needle
+  [ "$RC" -eq "$2" ] && echo "$OUT" | grep -q "$3" && ok "$1" || bad "$1 (rc=$RC out=$OUT)"
+}
+
+N=$(now_iso); O=$(old_iso)
+
+run "$(fx live "[$(claim sweep-A "$N")]")";                      expect "fresh claim is LIVE" 1 "CLAIM: LIVE sweep-A"
+run "$(fx exp "[$(claim sweep-A "$O")]")";                       expect "expired claim is FREE" 0 "CLAIM: FREE"
+run "$(fx rel "[$(claim sweep-A "$N"), $(release sweep-A "$N")]")"; expect "released claim is FREE" 0 "CLAIM: FREE"
+run "$(fx relother "[$(claim sweep-A "$N"), $(release sweep-B "$N")]")"; expect "release of another sweep does not free the claim" 1 "CLAIM: LIVE sweep-A"
+run "$(fx unkrel "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\nno sweep line\",\"updated_at\":\"$N\"}, {\"body\":\"<!-- FORGE:RECOVERY_CLAIM_RELEASED -->\\nno sweep line\",\"updated_at\":\"$N\"}]")"; expect "release with no sweep id does not free an id-less claim" 1 "CLAIM: LIVE unknown"
+run "$(fx own "[$(claim sweep-A "$N")]")" --exempt-sweep sweep-A; expect "own sweep id is exempt" 0 "CLAIM: FREE"
+run "$(fx other "[$(claim sweep-A "$N")]")" --exempt-sweep sweep-B; expect "other sweep id is not exempt" 1 "CLAIM: LIVE sweep-A"
+run "$(fx two "[$(claim sweep-A "$N"), $(claim sweep-B "$N")]")" --exempt-sweep sweep-A; expect "exempting A still sees live B" 1 "CLAIM: LIVE sweep-B"
+run "$(fx unk "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\nno sweep line\",\"updated_at\":\"$N\"}]")" --exempt-sweep sweep-A; expect "claim with no sweep id is never exempt" 1 "CLAIM: LIVE"
+run "$(fx unk2 "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\nno sweep line\",\"updated_at\":\"$N\"}]")" --exempt-sweep unknown; expect "--exempt-sweep unknown is rejected" 2 "CLAIM: ERROR"
+run "$(fx none '[]')";                                            expect "no comments is FREE" 0 "CLAIM: FREE"
+run "$(fx hb "[{\"body\":\"<!-- FORGE:HEARTBEAT -->\\nPhase 3\",\"updated_at\":\"$N\"}]")"; expect "heartbeat alone is not a recovery claim" 0 "CLAIM: FREE"
+run "$(fx bad "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\nno sweep line\",\"updated_at\":\"$N\"}]")"; expect "malformed claim fails closed (LIVE)" 1 "CLAIM: LIVE"
+run "$(fx nodate "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\n**Sweep: sweep-A**\",\"updated_at\":\"garbage\"}]")"; expect "unparsable updated_at fails closed (LIVE)" 1 "CLAIM: LIVE"
+
+OUT=$(MOCK_GH_FAIL=1 MOCK_GH_JSON=/dev/null bash "$CHECK" 7 -R o/r 2>/dev/null); RC=$?
+expect "gh outage is ERROR (exit 2)" 2 "CLAIM: ERROR"
+OUT=$(MOCK_GH_JSON="$(fx junk 'not json')" bash "$CHECK" 7 -R o/r 2>/dev/null); RC=$?
+expect "unparsable response is ERROR (exit 2)" 2 "CLAIM: ERROR"
+OUT=$(bash "$CHECK" 2>/dev/null); RC=$?;                          expect "no args is a usage error" 2 "CLAIM: ERROR"
+OUT=$(bash "$CHECK" 7 -R 2>/dev/null); RC=$?;                     expect "-R without value is a usage error" 2 "CLAIM: ERROR"
+
+echo "passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/verify-phase-trail.sh

@@ -9,7 +9,7 @@
 # verdict alone after phases were silently skipped.
 #
 # Usage:
-#   verify-phase-trail.sh <issue> -R <owner/repo> [--docs-only] [--code-diff] [--head-tree <sha>]
+#   verify-phase-trail.sh <issue> -R <owner/repo> [--docs-only] [--code-diff] [--head-tree <sha>] [--head-sha <sha>]
 #
 #   --docs-only   The diff is documentation-only; the FORGE:QUALITY_GATE marker
 #                 is not required.
@@ -22,6 +22,9 @@
 #                 An empty or non-hex value is a usage error (exit 2, fails closed).
 #                 Scope: this binds the PASS to the built tree; it is not tamper-proof, because the
 #                 pipeline agent posts under the same trusted identity and could compute the tree itself.
+#   --head-sha    Commit id (40 or 64 hex) of the head being gated. Enables the human break-glass
+#                 override (below); without it an override comment is never evaluated. An empty or
+#                 non-hex value is a usage error (exit 2, fails closed).
 #
 # Requirements by COMPLEXITY_BAND (read from the FORGE:FAST_PATH comment).
 # The authoritative table is the `case "$EFFECTIVE"` block below; this summary must be
@@ -38,9 +41,14 @@
 #   PHASE_TRAIL: PASS|FAIL|ERROR
 #   BAND: <band>
 #   MISSING: <marker> -> <phase to re-run>      (one line per missing artifact)
+#   PHASE_TRAIL: OVERRIDDEN                     (exit 0 via an accepted break-glass override)
+#   WAIVED: <marker list>                       (the MISSING set the override waived)
+#   OVERRIDE: approver=<login> head=<sha> missing=<list> reason=<sanitised>
+#                                               (the ONLY source callers use to record the override)
 #
-# Exit codes: 0 pass, 1 one or more artifacts missing, 2 could not
+# Exit codes: 0 pass (or accepted override), 1 one or more artifacts missing, 2 could not
 # read the issue (fails closed — an unreadable trail is never treated as a pass).
+# Exit 2 is NEVER overridable: override evaluation only runs on the exit-1 (MISSING) path.
 # Callers route on the exit code: 1 -> re-run the MISSING phases; 2 (or 127 when the
 # verifier itself cannot be resolved) -> infrastructure BLOCKED, never "missing phases".
 #
@@ -62,11 +70,36 @@
 # Identities outside that set -- e.g. a human with author_association CONTRIBUTOR/NONE/FIRST_TIME_CONTRIBUTOR
 # (an external contributor running the pipeline under their own login) -- are NOT trusted, so their
 # markers are ignored and the gate reports them MISSING. To accept such an identity add its login to
-# FORGE_TRAIL_TRUSTED_LOGINS, or widen FORGE_TRAIL_TRUSTED_ASSOCIATIONS (e.g. add CONTRIBUTOR). On FAIL the
+# FORGE_TRAIL_TRUSTED_LOGINS (do NOT widen FORGE_TRAIL_TRUSTED_ASSOCIATIONS to CONTRIBUTOR: that lets any
+# contributor forge FORGE:* trail markers). On FAIL the
 # script prints a NOTE when untrusted-author FORGE markers were seen, so this is diagnosable (#3123).
 # Limits: "Bot" trusts any GitHub App/bot that can comment on the repo (set
 # FORGE_TRAIL_TRUSTED_ASSOCIATIONS and FORGE_TRAIL_TRUSTED_LOGINS to tighten);
 # COLLABORATOR includes read-level collaborators; login matching is case-sensitive.
+# The override prefilter uses FORGE_TRAIL_OVERRIDE_ASSOCIATIONS (default: the trail list). Widen THAT variable,
+# not the trail list, for concealed-membership approvers; it never affects which FORGE markers count toward the
+# gate. Blast radius of widening FORGE_TRAIL_TRUSTED_ASSOCIATIONS: every listed association can forge trail markers.
+#
+# Break-glass override (#3152): a misfiring gate can be cleared by a HUMAN, never by the pipeline.
+# A comment whose body starts with `<!-- FORGE:PHASE_TRAIL_OVERRIDE -->` and carries the lines
+#   **Head**: <full head sha>
+#   **Missing**: <marker names, comma separated>
+#   **Reason**: <one line>
+# is honoured only when ALL of these hold (any error, null field or API failure rejects it and the
+# gate stays at exit 1; never a pass):
+#   - user.type == "User" (allowlist: Bots and null users are rejected) with a plain login;
+#   - updated_at == created_at (an edited comment is rejected: tamper evidence);
+#   - the author has repo permission admin or write (collaborators/<login>/permission), not mere
+#     org membership or read access;
+#   - the author is NOT a pipeline identity: FORGE_TRAIL_PIPELINE_LOGINS (comma-separated, case-insensitive)
+#     plus the author of every trusted FORGE marker comment (BUILDER, INVESTIGATOR, CONTRACT, ...), so a
+#     pipeline running under a human token cannot approve its own gate. A solo operator therefore needs a
+#     second human with write access to post the override;
+#   - **Head** equals --head-sha and **Missing** equals the current MISSING marker-name set exactly
+#     (a new commit or a different failure invalidates it);
+#   - created_at is later than the latest trusted FORGE:BUILDER:COMPLETE update time.
+# The reason is sanitised (control chars stripped, comment markers neutralised, whitespace collapsed,
+# capped at 200 chars); an empty reason rejects the override.
 # END-HELP (`-h` prints the header up to this line; keep it last)
 
 set -uo pipefail
@@ -77,6 +110,8 @@ DOCS_ONLY=0
 CODE_DIFF=0
 HEAD_TREE=""
 HEAD_TREE_SET=0
+HEAD_SHA=""
+HEAD_SHA_SET=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -88,6 +123,9 @@ while [ $# -gt 0 ]; do
     --head-tree)
       if [ $# -lt 2 ]; then echo "PHASE_TRAIL: ERROR"; echo "usage error: $1 needs a value" >&2; exit 2; fi
       HEAD_TREE="$2"; HEAD_TREE_SET=1; shift 2 ;;
+    --head-sha)
+      if [ $# -lt 2 ]; then echo "PHASE_TRAIL: ERROR"; echo "usage error: $1 needs a value" >&2; exit 2; fi
+      HEAD_SHA="$2"; HEAD_SHA_SET=1; shift 2 ;;
     -h|--help) awk 'NR >= 5 { if (/^# END-HELP/) exit; print }' "$0"; exit 0 ;;
     *)
       if [ -z "$ISSUE" ] && [[ "$1" =~ ^[0-9]+$ ]]; then ISSUE="$1"; shift
@@ -98,7 +136,7 @@ done
 
 if [ -z "$ISSUE" ] || [ -z "$REPO" ]; then
   echo "PHASE_TRAIL: ERROR"
-  echo "usage: verify-phase-trail.sh <issue> -R <owner/repo> [--docs-only] [--code-diff] [--head-tree <sha>]" >&2
+  echo "usage: verify-phase-trail.sh <issue> -R <owner/repo> [--docs-only] [--code-diff] [--head-tree <sha>] [--head-sha <sha>]" >&2
   exit 2
 fi
 if [ "$HEAD_TREE_SET" = "1" ]; then
@@ -111,6 +149,16 @@ if [ "$HEAD_TREE_SET" = "1" ]; then
   fi
 fi
 
+if [ "$HEAD_SHA_SET" = "1" ]; then
+  # Fail closed: a caller that could not resolve the head passes an empty value and must not silently skip the binding.
+  HEAD_SHA=$(printf '%s' "$HEAD_SHA" | tr 'A-F' 'a-f')
+  if ! [[ "$HEAD_SHA" =~ ^([0-9a-f]{40}|[0-9a-f]{64})$ ]]; then
+    echo "PHASE_TRAIL: ERROR"
+    echo "usage error: --head-sha needs a 40 or 64 hex commit id" >&2
+    exit 2
+  fi
+fi
+
 RAW=$(gh api "repos/${REPO}/issues/${ISSUE}/comments" --paginate 2>/dev/null) || {
   echo "PHASE_TRAIL: ERROR"
   echo "could not read comments for ${REPO}#${ISSUE}" >&2
@@ -130,6 +178,10 @@ RAW=$(printf '%s' "$RAW" | jq -s 'if all(.[]; type == "array" and all(.[]; type
 # One line per comment, newlines folded to \x1f so a marker and its sentinel can
 # be matched within the SAME comment.
 TRUSTED_ASSOC="${FORGE_TRAIL_TRUSTED_ASSOCIATIONS-OWNER,MEMBER,COLLABORATOR}"
+# Separate trust decision (forge#3350): the break-glass override prefilter has its own list so it can be widened
+# (e.g. CONTRIBUTOR for concealed-membership approvers) without loosening the trail-marker gate. Defaults to the
+# trail list; ${VAR-default} (no colon) so an explicitly empty value yields no override candidates (fail closed).
+OVERRIDE_ASSOC="${FORGE_TRAIL_OVERRIDE_ASSOCIATIONS-$TRUSTED_ASSOC}"
 TRUSTED_LOGINS="${FORGE_TRAIL_TRUSTED_LOGINS-}"
 COMMENTS=$(printf '%s' "$RAW" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" '
   ($assoc | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $A
@@ -263,6 +315,133 @@ if [ "${#MISSING[@]}" -eq 0 ]; then
   exit 0
 fi
 
+# --- Break-glass override (#3152) ---------------------------------------------------------------
+# Reached ONLY with a non-empty MISSING set (exit-1 path); every `exit 2` above precedes it.
+# Prints the OVERRIDE/WAIVED lines and returns 0 only when a comment passes every rule; any failure
+# (jq error, permission API error, empty field) returns 1 and the caller falls through to FAIL.
+# Name set normaliser shared by BOTH sides of the comparison: drops ` -> action` and `(qualifier)`,
+# trims, de-duplicates, sorts, joins with commas. bash 3.2/BSD portable.
+norm_set() {
+  sed -e 's/ -> .*$//' -e 's/([^)]*)//g' -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' \
+    | grep -v '^$' | LC_ALL=C sort -u | paste -sd, -
+}
+
+evaluate_override() {
+  [ "$HEAD_SHA_SET" = "1" ] || return 1
+  local cur_set cands pipeline_logins login created head missing reason perm n=0 total=0 seen_logins="" llogin
+  cur_set=$(printf '%s\n' "${MISSING[@]}" | norm_set) || return 1
+  [ -n "$cur_set" ] || return 1
+  # BUILDER exists but its completion time is unknown -> cannot prove the override is newer: reject.
+  if has '<!-- FORGE:BUILDER -->' && [ -z "$BUILD_AT" ]; then return 1; fi
+  # Pipeline identity set (configured + derived): authors of trusted FORGE marker comments other than overrides.
+  # The token this verifier runs under is the pipeline's identity too (forge#3269): a pipeline using a human
+  # token with no markers yet must not approve its own override. Lookup failure adds nothing (derived set still applies).
+  local self_login extra_logins marker_floor
+  self_login=$(gh api user --jq '.login' 2>/dev/null || true)
+  case "$self_login" in *[!A-Za-z0-9_-]*) self_login="" ;; esac
+  extra_logins="${FORGE_TRAIL_PIPELINE_LOGINS-}${self_login:+,$self_login}"
+  pipeline_logins=$(printf '%s' "$RAW" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg extra "$extra_logins" '
+    ($assoc | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $A
+    | ($logins | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $L
+    | ($extra | split(",") | map(gsub("^\\s+|\\s+$"; "") | ascii_downcase) | map(select(length > 0))) as $E
+    | ( [ .[]
+          | select(
+              ((.author_association // "") as $x | $A | index($x) != null)
+              or ((.user.type // "") == "Bot")
+              or ((.user.login // "") as $x | $L | index($x) != null))
+          | select((.body // "") | startswith("<!-- FORGE:") and (startswith("<!-- FORGE:PHASE_TRAIL_OVERRIDE -->") | not))
+          | (.user.login // empty) | ascii_downcase ] + $E ) | unique | .[]' 2>/dev/null) || return 1
+  # Time floor (forge#3271): the latest trusted BUILDER:COMPLETE. With none, fall back to the newest trusted
+  # non-override FORGE marker so an override still has to post-date the pipeline's own activity.
+  marker_floor="$BUILD_AT"
+  if [ -z "$marker_floor" ]; then
+    marker_floor=$(printf '%s' "$RAW" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" '
+      ($assoc | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $A
+      | ($logins | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $L
+      | [ .[]
+          | select(((.author_association // "") as $x | $A | index($x) != null)
+                   or ((.user.type // "") == "Bot")
+                   or ((.user.login // "") as $x | $L | index($x) != null))
+          | select((.body // "") | startswith("<!-- FORGE:") and (startswith("<!-- FORGE:PHASE_TRAIL_OVERRIDE -->") | not))
+          | .created_at // empty ] | sort | .[-1] // empty' 2>/dev/null) || return 1
+  fi
+  # Candidates, newest first, as TSV: login created_at head missing reason (reason last, others never empty).
+  # The author_association prefilter uses its own list ($OVERRIDE_ASSOC, default = trail list) and is only an
+  # optimization (forge#3279): the permission API stays authoritative. A real write/admin approver with concealed
+  # org membership can show CONTRIBUTOR/NONE and is filtered out here; widen FORGE_TRAIL_OVERRIDE_ASSOCIATIONS to
+  # accept them (never the trail list). An empty list yields no candidates (fail closed). Filtered candidates are counted in a NOTE.
+  # One jq pass (forge#3351): the eligibility predicate is defined once (`eligible`); the first output line is the
+  # count of eligible comments dropped by the association prefilter, the rest are the candidate TSV rows.
+  local assoc_dropped out
+  out=$(printf '%s' "$RAW" | jq -r --arg assoc "$OVERRIDE_ASSOC" --arg bt "$marker_floor" '
+    ($assoc | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $A
+    | def clean: explode | map(select(. >= 32 and . != 127 and (. < 128 or . > 159) and (. < 8203 or . > 8207) and (. < 8232 or . > 8238) and (. < 8288 or . > 8297) and . != 65279)) | implode;
+    def eligible:
+      select((.body // "") | startswith("<!-- FORGE:PHASE_TRAIL_OVERRIDE -->"))
+      | select((.user.type // "") == "User")
+      | select(((.user.login // "") | test("^[A-Za-z0-9_-]+$")))
+      | select((.created_at // "") != "" and (.updated_at // "") != "" and .created_at == .updated_at)
+      | select($bt == "" or .created_at > $bt);
+    def assoc_ok: (.author_association // "") as $x | $A | index($x) != null;
+    ( [ .[] | eligible | select(assoc_ok | not) ] | length ) as $dropped
+    | ( [ .[]
+        | eligible
+        | select(assoc_ok)
+        | (.body | split("\n") | map(sub("\r$"; ""))) as $ln
+        | { login: .user.login, at: .created_at,
+            head: ([$ln[] | capture("^\\*\\*Head\\*\\*: *(?<v>[0-9A-Fa-f]{40,64}) *$")? | .v] | .[0] // "-"),
+            missing: ([$ln[] | capture("^\\*\\*Missing\\*\\*: *(?<v>.+)$")? | .v] | .[0] // "-"),
+            reason: ([$ln[] | capture("^\\*\\*Reason\\*\\*: *(?<v>.*)$")? | .v] | .[0] // "")
+              | clean | gsub("<!--"; "<!-/-") | gsub("-->"; "-/->") | gsub("`"; "'"'"'") | gsub("@"; "(at)")
+              | gsub("\\s+"; " ") | sub("^ "; "") | sub(" $"; "") | .[0:200] } ]
+      | sort_by(.at) | reverse ) as $rows
+    | "#DROPPED\t\($dropped)",
+      ($rows[] | [.login, .at, .head, .missing, (if .reason == "" then "-" else .reason end)] | @tsv)' 2>/dev/null) || return 1
+  assoc_dropped=$(printf '%s\n' "$out" | head -n 1 | cut -f2)
+  case "$assoc_dropped" in ''|*[!0-9]*) assoc_dropped=0 ;; esac
+  if [ "$assoc_dropped" -gt 0 ]; then echo "NOTE: ${assoc_dropped} override candidate(s) ignored: author_association not in override-approver set" >&2; fi
+  cands=$(printf '%s\n' "$out" | tail -n +2)
+  [ -n "$cands" ] || return 1
+  while IFS=$'\t' read -r login created head missing reason; do
+    [ -n "$login" ] || continue
+    [ "$reason" != "-" ] && [ -n "$reason" ] || continue
+    reason=$(printf '%s' "$reason" | tr -d '[:cntrl:]')   # belt and braces: cntrl (incl. ESC) stripped again
+    [ -n "$reason" ] || continue
+    [ "$(printf '%s' "$head" | tr 'A-F' 'a-f')" = "$HEAD_SHA" ] || continue
+    [ "$(printf '%s' "$missing" | tr ',' '\n' | norm_set)" = "$cur_set" ] || continue
+    if printf '%s\n' "$pipeline_logins" | grep -Fx -- "$(printf '%s' "$login" | tr 'A-Z' 'a-z')" >/dev/null; then continue; fi
+    # forge#3279/#3306: dedupe distinct logins (bash 3.2-portable newline list, no associative arrays); a login seen
+    # before was already rejected (an accepted one returns), so repeat comments cost no slot and no API call.
+    # Cap accounting: a DEFINITIVE negative (read/triage/none) is free so read-level members cannot crowd out an older
+    # real approver; only UNREADABLE lookups spend the 5-slot error cap, and 25 distinct lookups is a hard ceiling.
+    llogin=$(printf '%s' "$login" | tr 'A-Z' 'a-z')
+    if printf '%s\n' "$seen_logins" | grep -Fx -- "$llogin" >/dev/null; then continue; fi
+    total=$((total+1)); [ "$total" -le 25 ] || { echo "NOTE: break-glass override: more than 25 distinct candidate logins; extra ones ignored" >&2; break; }   # bound API calls
+    seen_logins="${seen_logins}${llogin}"$'\n'
+    # Login already matched ^[A-Za-z0-9_-]+$ in jq, so it is safe to interpolate into the API path.
+    perm=$(gh api "repos/${REPO}/collaborators/${login}/permission" 2>/dev/null | jq -r '.permission // empty' 2>/dev/null) || perm=""
+    case "$perm" in
+      admin|write) ;;
+      "")
+        echo "NOTE: break-glass override by ${login} rejected: permission='unreadable' (needs admin/write; the lookup needs a token with push access)" >&2
+        n=$((n+1)); [ "$n" -le 5 ] || { echo "NOTE: break-glass override: more than 5 unreadable permission lookups; extra candidates ignored" >&2; break; }
+        continue ;;
+      *) echo "NOTE: break-glass override by ${login} rejected: permission='${perm}' (needs admin/write)" >&2; continue ;;
+    esac
+    echo "PHASE_TRAIL: OVERRIDDEN"
+    echo "BAND: ${BAND:-UNKNOWN}"
+    echo "WAIVED: ${cur_set}"
+    echo "OVERRIDE: approver=${login} head=${HEAD_SHA} missing=${cur_set} reason=${reason}"
+    return 0
+  done <<< "$cands"
+  return 1
+}
+
+if evaluate_override; then
+  [ -n "${BAND_NOTE:-}" ] && echo "NOTE: $BAND_NOTE"
+  exit 0
+fi
+
 echo "PHASE_TRAIL: FAIL"
 echo "BAND: ${BAND:-UNKNOWN}"
 for m in "${MISSING[@]}"; do echo "MISSING: $m"; done