@soleur/opencode 0.0.0-stage → 1.0.0

package/scripts/alpha-metrics.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+#
+# alpha-metrics.sh -- print the aggregate a tester pastes back at checkpoint.
+#
+# Usage: run inside the project repo:  bash plugins/soleur/scripts/alpha-metrics.sh
+#
+# Reads .soleur/decisions.jsonl (and the rotated .1) at the git root and prints
+# aggregate counts ONLY: total lines, per-skill / per-agent_domain / per-harness
+# breakdowns, first/last timestamps. Metadata is already allowlisted at write
+# time, but this script still prints counts and fields only — never raw lines.
+#
+# Missing or empty output is a SIGNAL, not a zero:
+#   SOLEUR_EMIT_ABSENT -- no log exists (stale install / emit never ran)
+#   SOLEUR_EMIT_EMPTY  -- log exists with zero records (kill-switch set,
+#                         unwritable dir, or a brand-new install)
+# Neither means "the tester did nothing". Never report absence as zero usage.
+#
+# Portability: awk/grep/sed/wc/sort/head only — stock macOS bash 3.2-safe.
+
+set -uo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=plugins/soleur/scripts/resolve-git-root.sh
+. "$DIR/resolve-git-root.sh" 2>/dev/null || {
+  echo "SOLEUR_EMIT_ABSENT — not inside a git repository"
+  exit 0
+}
+
+LOG_DIR="$GIT_ROOT/.soleur"
+LOG="$LOG_DIR/decisions.jsonl"
+ROT="$LOG.1"
+
+if [ ! -f "$LOG" ] && [ ! -f "$ROT" ]; then
+  echo "SOLEUR_EMIT_ABSENT — no decision log at .soleur/decisions.jsonl"
+  echo "(a stale plugin install or emit has never fired; this is NOT proof of zero usage)"
+  exit 0
+fi
+
+if [ ! -s "$LOG" ] && [ ! -s "$ROT" ]; then
+  echo "SOLEUR_EMIT_EMPTY — the log exists but holds no records"
+  echo "(kill-switch SOLEUR_DISABLE_DECISION_LOG, an unwritable .soleur, or a brand-new install)"
+  exit 0
+fi
+
+# Merge current + rotated; each line is one allowlisted JSON object.
+INPUT="$(cat "$LOG" "$ROT" 2>/dev/null)"
+
+total="$(printf '%s\n' "$INPUT" | grep -c '^{"v":' )"
+lines="$(printf '%s\n' "$INPUT" | grep -c .)"
+malformed=$((lines - total))
+first="$(printf '%s\n' "$INPUT" | sed -n 's/.*"ts":"\([^"]*\)".*/\1/p' | sort | head -1)"
+last="$(printf '%s\n' "$INPUT" | sed -n 's/.*"ts":"\([^"]*\)".*/\1/p' | sort | tail -1)"
+
+echo "=== .soleur/decisions.jsonl aggregate ==="
+echo "records:  $total"
+[ "$malformed" -gt 0 ] && echo "malformed: $malformed line(s) skipped (corrupt log — not counted)"
+echo "first:    ${first:-unknown}"
+echo "last:     ${last:-unknown}"
+echo
+
+count_field() { # $1 = json field name
+  printf '%s\n' "$INPUT" \
+    | sed -n "s/.*\"$1\":\"\([^\"]*\)\".*/\1/p" \
+    | grep -v '^$' \
+    | sort | uniq -c | sort -rn \
+    | awk '{printf "  %-6s %s\n", $1, $2}'
+}
+
+echo "by event:";        count_field event
+echo "by label:";        count_field label
+echo "by skill:";        count_field skill
+echo "by agent_domain:"; count_field agent_domain
+echo "by harness:";      count_field harness
+
+echo
+echo "Knowledge-base growth (run in this repo):"
+echo "  git log --since=<onboard-date> --name-only -- knowledge-base/ | grep -c '^knowledge-base/'"
+exit 0

package/scripts/alpha-metrics.test.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# Tests for alpha-metrics.sh — the checkpoint aggregate printer.
+#
+# Load-bearing contract: ABSENT/EMPTY markers must render as signals, never as
+# a zero count. A tester who did nothing and a tester whose emit never ran are
+# different worlds; the print must not conflate them.
+
+set -uo pipefail
+export TMPDIR="${TMPDIR:-/var/tmp}"
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SUT="$DIR/alpha-metrics.sh"
+EMIT="$DIR/emit-decision.sh"
+
+# trap BEFORE sourcing test-helpers.sh so the helpers' composed EXIT trap
+# (<prior>; _soleur_sb_cleanup) stacks on ours instead of being clobbered by it.
+TMP="$(mktemp -d -t alpham.XXXXXXXX)" || { echo "mktemp failed" >&2; exit 2; }
+trap 'rm -rf "$TMP"' EXIT
+
+# shellcheck source=plugins/soleur/test/test-helpers.sh
+source "$DIR/../test/test-helpers.sh" || { echo "FATAL: could not source test-helpers.sh" >&2; exit 2; }
+set +e -uo pipefail
+
+passes=0
+fails=0
+CASES=0
+
+pass() { passes=$((passes + 1)); printf '  ok   %s\n' "$1"; }
+fail() { fails=$((fails + 1)); printf '  FAIL %s\n' "$1"; [[ -n "${2:-}" ]] && printf '       %s\n' "$2"; return 0; }
+assert() {
+  CASES=$((CASES + 1))
+  if eval "$2"; then pass "$1"; else fail "$1" "${3:-$2}"; fi
+}
+
+printf '\n=== alpha-metrics.sh ===\n\n'
+[[ -f "$SUT" ]] || { printf '\n[FATAL] SUT missing at %s\n' "$SUT" >&2; exit 1; }
+
+new_repo() { # $1 = name
+  local d="$TMP/$1"; mkdir -p "$d"
+  git -C "$d" init -q -b main
+  git -C "$d" config user.email soleur-test@example.invalid
+  git -C "$d" config user.name  "Soleur Test"
+  git -C "$d" config commit.gpgsign false
+  git -C "$d" commit -q --allow-empty -m "base"
+  printf '%s' "$d"
+}
+
+# --- ABSENT: no log at all --------------------------------------------------
+
+RA="$TMP/no-log"; new_repo no-log >/dev/null
+out="$(cd "$RA" && bash "$SUT")"
+assert "missing log -> SOLEUR_EMIT_ABSENT" "[[ '$out' == *SOLEUR_EMIT_ABSENT* ]]"
+assert "absent never prints a zero count" "! printf '%s' '$out' | grep -c >/dev/null 'records:  *0'"
+
+# --- EMPTY: log exists, zero records -----------------------------------------
+
+RB="$TMP/empty-log"; new_repo empty-log >/dev/null
+mkdir -p "$RB/.soleur"; touch "$RB/.soleur/decisions.jsonl"
+out="$(cd "$RB" && bash "$SUT")"
+assert "empty log -> SOLEUR_EMIT_EMPTY" "[[ '$out' == *SOLEUR_EMIT_EMPTY* ]]"
+assert "empty never prints a zero count" "! printf '%s' '$out' | grep -c >/dev/null 'records:  *0'"
+
+# --- POPULATED: real emits aggregate -----------------------------------------
+
+RC="$TMP/pop"; new_repo pop >/dev/null
+( cd "$RC"
+  bash "$EMIT" --event route_decision --label work
+  bash "$EMIT" --event route_decision --label brainstorm
+  bash "$EMIT" --event route_decision --label work
+  bash "$EMIT" --event tool_invocation --label flag-list --skill flag-list --agent_domain ops )
+out="$(cd "$RC" && bash "$SUT")"
+assert "counts 4 records" "printf '%s' '$out' | grep -c >/dev/null 'records:  *4'"
+assert "per-event count present" "printf '%s' '$out' | grep -A3 'by event:' | grep -c >/dev/null 'route_decision'"
+assert "per-label count shows work=2" "printf '%s' '$out' | grep -A5 'by label:' | grep -cE >/dev/null '^ *2 +work'"
+assert "per-domain count shows ops=1" "printf '%s' '$out' | grep -A4 'by agent_domain:' | grep -c >/dev/null 'ops'"
+assert "per-harness count is non-empty" "printf '%s' '$out' | grep -A3 'by harness:' | grep -cE >/dev/null '^ *[0-9]+ +[a-zA-Z]'"
+assert "first/last timestamps printed" "printf '%s' '$out' | grep -c >/dev/null 'first:' && printf '%s' '$out' | grep -c >/dev/null 'last:'"
+assert "KB-growth instruction printed" "printf '%s' '$out' | grep -c >/dev/null 'git log --since'"
+
+# --- ROTATED: merged read ----------------------------------------------------
+
+RD="$TMP/rot"; new_repo rot >/dev/null
+( cd "$RD" && bash "$EMIT" --event route_decision --label one )
+printf '{"v":1,"ts":"2026-01-01T00:00:00Z","event":"route_decision","label":"old","skill":"","agent_domain":"","harness":"claude","session_id":"s","plugin_sha":"x","repo_hash":"h"}\n' > "$RD/.soleur/decisions.jsonl.1"
+out="$(cd "$RD" && bash "$SUT")"
+assert "rotated lines merge into the count" "printf '%s' '$out' | grep -c >/dev/null 'records:  *2'"
+
+# --- ORDERING: first/last carry VALUES, not just labels ----------------------
+
+RE="$TMP/order"; new_repo order >/dev/null
+mkdir -p "$RE/.soleur"
+printf '%s\n' '{"v":1,"ts":"2026-03-05T00:00:00Z","event":"route_decision","label":"b","skill":"","agent_domain":"","harness":"x","session_id":"s","plugin_sha":"p","repo_hash":"h"}' \
+  '{"v":1,"ts":"2026-03-01T00:00:00Z","event":"route_decision","label":"a","skill":"","agent_domain":"","harness":"x","session_id":"s","plugin_sha":"p","repo_hash":"h"}' \
+  > "$RE/.soleur/decisions.jsonl"
+out="$(cd "$RE" && bash "$SUT")"
+assert "first: carries the EARLIEST ts (not just the label)" \
+  "printf '%s' '$out' | grep -c >/dev/null 'first:    2026-03-01'"
+assert "last: carries the LATEST ts" \
+  "printf '%s' '$out' | grep -c >/dev/null 'last:     2026-03-05'"
+
+# --- CORRUPTION: a malformed line is surfaced, not silently counted ----------
+
+RF="$TMP/bad"; new_repo bad >/dev/null
+mkdir -p "$RF/.soleur"
+printf '%s\n' '{"v":1,"ts":"2026-03-01T00:00:00Z","event":"route_decision","label":"ok","skill":"","agent_domain":"","harness":"x","session_id":"s","plugin_sha":"p","repo_hash":"h"}' \
+  'garbage-not-json' \
+  > "$RF/.soleur/decisions.jsonl"
+out="$(cd "$RF" && bash "$SUT")"
+assert "malformed lines are reported, not silently dropped" \
+  "printf '%s' '$out' | grep -c >/dev/null 'malformed: 1'"
+
+printf '\n=== alpha-metrics: %d passed, %d failed (of %d) ===\n' "$passes" "$fails" "$CASES"
+# Anti-vacuity floor (#7408 class): a suite that ran nothing must not exit green.
+[[ "$fails" -eq 0 && "$CASES" -ge 15 ]]

package/scripts/ancestor-signal-helpers.baseline.txt

@@ -0,0 +1,16 @@
+# ancestor-signal baseline: one row per gated finding, <path> TAB <class> TAB <normalised line>.
+# Classes: W ancestor walk that signals (must read bounded=yes), P signal to the parent, G all-process signal.
+# Maintenance: an in-place replacement of an existing row (same path and class, e.g. after an unrelated edit of
+# that line) is allowed; a net addition needs a reviewer's read; otherwise the file may only shrink. A stale row
+# (no live line) and an unbounded W are red. bounded=yes is LEXICAL (a non-comment SOLEUR_TEST_SUITE_PID
+# comparison with exit, break or return near the walk), not proof of containment.
+# Regenerate: python3 plugins/soleur/scripts/scan-ancestor-signal-helpers.py --write-baseline <this file>
+# (overwrites the whole file: review the diff row by row).
+apps/web-platform/infra/arm-heartbeats.test.sh	P	if [[ "$seen" -ge "$FAKE_CUT_AFTER" ]]; then kill -9 "$PPID" 2>/dev/null; exit 0; fi
+apps/web-platform/infra/git-data-luks-reopen.test.sh	P	[ -f "$FX/luksopen_kill" ] && kill -TERM "$PPID"
+apps/web-platform/infra/run-registered-suites.test.sh	P	kill -9 "$_shim" 2>/dev/null
+apps/web-platform/infra/workspaces-boot-unlock.test.sh	P	[ -f "$FX/luksopen_kill" ] && kill -TERM "$PPID"
+apps/web-platform/infra/workspaces-luks-provision.test.sh	P	[ -f "$st/crash_after_luksFormat" ] && kill -9 "$PPID"
+apps/web-platform/infra/workspaces-luks-provision.test.sh	P	[ -f "$st/crash_after_mkfs" ] && kill -9 "$PPID"
+plugins/soleur/scripts/resolve-regenerable-conflicts.test.sh	W	p=$(awk '{print $4}' "/proc/$p/stat" 2>/dev/null)
+plugins/soleur/test/roadmap-reconcile.test.sh	W	top=$p; p=$(awk '{print $4}' "/proc/$p/stat")

package/scripts/audit-flag-flip.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Shared WORM audit-append helper for the flag-tooling skills (#4581 PR-1).
+#
+# Appends a row to public.flag_flip_audit via the SECURITY DEFINER PostgREST RPC
+# `audit_flag_flip` (migration 071), replacing the prior `psql` binary dependency
+# so the sanctioned path runs on any machine (no psql/sudo).
+#
+# Sourced by:
+#   plugins/soleur/skills/flag-create/scripts/create.sh
+#   plugins/soleur/skills/flag-delete/scripts/delete.sh
+#   plugins/soleur/skills/flag-set-role/scripts/flip.sh
+#   plugins/soleur/skills/user-set-role/scripts/set-role.sh
+#
+# Contract:
+#   audit_flag_flip_rpc <url> <srk> <flag> <env> <target> <action> <before> <after> <actor>
+#
+#   <url>    SUPABASE_URL of the audit DB (callers resolve from Doppler -c dev,
+#            matching the historical DATABASE_URL_POOLER -c dev audit target).
+#   <srk>    SUPABASE_SERVICE_ROLE_KEY for <url> (the RPC is GRANTed to service_role only).
+#   <before>/<after>  LITERAL JSON tokens: `true` | `false` | `null`. Passed via
+#                     `jq --argjson` so they reach the bool columns as JSON bool/null,
+#                     not strings (a `--arg` string fails PostgREST bool coercion).
+#
+# Approval method (#8486, ADR-249): the body carries p_approval_method:"tty-ack"
+# (migration 140) ONLY when the operator-script library's class-2 ack has set the
+# plain shell variable SOLEUR_OP_ACKED=tty-ack in this process. Without it the
+# helper refuses with rc 4 before any request, so an audit append placed before
+# the ack fails closed and the WORM value means "the ack returned here". The
+# value is self-reported by the script, not proof that a person typed.
+#
+# Behavior: append-before-flip — the caller MUST call this BEFORE any Flagsmith /
+# Supabase mutation, and abort the flip on a non-zero return. Returns:
+#   0  audit row written (echoes the row uuid on stdout)
+#   4  audit append failed (non-2xx, empty body, or missing/null id) — caller exits 4
+#
+# Requires: curl, jq.
+audit_flag_flip_rpc() {
+  local url="$1" srk="$2" flag="$3" env="$4" target="$5" action="$6" before="$7" after="$8" actor="$9"
+  local body resp code id
+
+  # Observability (review #8650): the WORM audit trail failing is the one failure
+  # this script's own contract exists to make impossible to miss. stderr alone is
+  # sufficient for an ack-refusal (the operator is at the keyboard that just typed
+  # `yes`), but a durable, names-not-values ledger row survives past a scrolled
+  # terminal. `soleur_op_ledger_note` is defined by operator-script.sh, which every
+  # caller sources before this function is ever invoked (append-before-flip runs
+  # after the ack) — guard with `declare -F` so this stays safe if that assumption
+  # ever stops holding.
+  # Always returns 0 — this is bookkeeping around a failure already being
+  # reported, and running under the caller's `set -e` a nonzero return here
+  # would abort the function before its own `return 4` executes.
+  _audit_failed_marker() {
+    printf 'SOLEUR_BOOTSTRAP_AUDIT_APPEND_FAILED reason=%s\n' "$1" >&2
+    if declare -F soleur_op_ledger_note >/dev/null 2>&1; then
+      soleur_op_ledger_note audit_append_failed "$flag" "$1" || true
+    fi
+    return 0
+  }
+
+  if [[ "${SOLEUR_OP_ACKED:-}" != "tty-ack" ]]; then
+    echo "FATAL: audit append before the ack — the class-2 yes prompt has not returned in this process (#8486)" >&2
+    _audit_failed_marker no-ack
+    return 4
+  fi
+  command -v jq >/dev/null   || { echo "FATAL: jq not found (audit append)" >&2; _audit_failed_marker no-jq; return 4; }
+  command -v curl >/dev/null || { echo "FATAL: curl not found (audit append)" >&2; _audit_failed_marker no-curl; return 4; }
+
+  # --argjson for the bool/null args; --arg for the text args.
+  body=$(jq -nc \
+    --arg  f  "$flag"   --arg e  "$env"    --arg t "$target" \
+    --arg  a  "$action" --arg ac "$actor" --arg am "$SOLEUR_OP_ACKED" \
+    --argjson b  "$before" --argjson af "$after" \
+    '{p_flag_name:$f, p_env:$e, p_target:$t, p_action:$a, p_before_bool:$b, p_after_bool:$af, p_actor:$ac, p_approval_method:$am}') \
+    || { echo "FATAL: failed to build audit RPC body (bad before/after token: '$before'/'$after')" >&2; _audit_failed_marker bad-body; return 4; }
+
+  # Token-shape guard (never echoes the value): the key is written into curl's stdin
+  # config below, so a quote or newline in it would inject a config directive. An
+  # unusable key makes zero curl calls and the same failure outcome (rc 4) as any other
+  # failed append, never success.
+  _audit_bearer_ok() { local LC_ALL=C; case "${1:-}" in ''|*[!A-Za-z0-9._~+/=-]*) return 1 ;; esac; }
+  _audit_bearer_ok "$srk" \
+    || { echo "FATAL: audit append key has an unexpected shape (not sent)" >&2; _audit_failed_marker bad-key-shape; return 4; }
+
+  # The service-role key rides curl's stdin config channel (both the apikey and the
+  # Authorization header), never its argument list.
+  resp=$(curl --disable --noproxy '*' -sS -w '\n%{http_code}' -X POST \
+    -H "Content-Type: application/json" -H "Accept: application/json" \
+    --config - \
+    "${url}/rest/v1/rpc/audit_flag_flip" -d "$body" \
+    < <(printf 'header = "apikey: %s"\nheader = "Authorization: Bearer %s"\n' "$srk" "$srk")) \
+    || { echo "FATAL: audit RPC request failed (transport error)" >&2; _audit_failed_marker curl-error; return 4; }
+
+  code=$(printf '%s' "$resp" | tail -n1)
+  body=$(printf '%s' "$resp" | sed '$d')
+  [[ "$code" =~ ^2[0-9][0-9]$ ]] \
+    || { echo "FATAL: audit RPC non-2xx (HTTP $code): $body" >&2; _audit_failed_marker "http-$code"; return 4; }
+
+  # RETURNS uuid -> PostgREST emits a bare JSON scalar; array branch is dead-but-safe.
+  # `|| id=""` makes the no-id path deterministic under the caller's `set -e` (a jq
+  # parse failure on garbage/empty body would otherwise abort the subshell before the
+  # guard); the uuid-shape match then rejects empty/null/non-uuid (incl. a 2xx `{}`).
+  id=$(printf '%s' "$body" | jq -r 'if type=="array" then .[0] else . end' 2>/dev/null) || id=""
+  [[ "$id" =~ ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ ]] \
+    || { echo "FATAL: audit RPC returned no valid uuid: $body" >&2; _audit_failed_marker no-valid-uuid; return 4; }
+
+  printf '%s' "$id"
+}

package/scripts/check-red-on-main.sh

@@ -0,0 +1,316 @@
+#!/usr/bin/env bash
+# check-red-on-main.sh "<check-name>" --run-id <failing-run-id> [--report] [--repo owner/repo]
+# check-red-on-main.sh --self-test
+# check-red-on-main.sh --help
+#
+# WHY THIS EXISTS (#9402). A PR whose check is red because MAIN is red pays rerun cycles and
+# autonomous-fix attempts for a failure it did not cause -- PR #9339 paid three reruns of
+# `deploy-script-tests (1/4)` while that leg was red on main. "Confirmed pre-existing" was an
+# agent judgment call with no mechanical probe; this script is the probe. It answers one
+# question: did the newest completed main-branch run of the SAME workflow that exercised a job
+# of the EXACT same name conclude it non-green?
+#
+# HOW IT DECIDES.
+#   * The failing check's workflow is resolved through the run it failed in:
+#     `gh api repos/{o}/{r}/actions/runs/<run-id>` -> .workflow_id. `gh pr checks`' `link` field
+#     already carries `actions/runs/<run-id>`.
+#   * Up to 5 completed main-branch runs of that workflow are listed, newest first
+#     (`actions/workflows/<id>/runs?branch=main&status=completed&per_page=5`).
+#   * In each run the job named EXACTLY <check-name> is looked up. Matrix suffixes like `(1/4)`
+#     are part of the name -- the parent `deploy-script-tests` never answers for the leg, and a
+#     prefix match would read a green parent as a green leg.
+#   * skipped/absent jobs are NOT evidence: a path-filtered main push that never ran the job
+#     says nothing, so the scan continues to older runs in the window.
+#   * The FIRST run where the job reached a real conclusion decides:
+#       red-on-main   -- conclusion in {failure, timed_out, cancelled, startup_failure}
+#       green-on-main -- conclusion in {success, neutral}
+#       no-evidence   -- no run in the window exercised the job -> NOT quarantined
+#     `cancelled` is red by the same `!= 'success'` convention notify-main-failure uses;
+#     `startup_failure` is red because the runner never got to measure the job. `skipped`,
+#     `stale`, and `action_required` are not evidence -- the job never produced a verdict
+#     on code, so the scan continues to older runs in the window.
+#
+# EXIT CODES (the contract every caller branches on).
+#   0  green-on-main   the check is healthy on main -- this PR's red is its own
+#   1  red-on-main     same-named job is red on the newest exercising main run -> quarantine
+#   2  no-evidence     no main run in the window exercised the job -> NOT quarantined
+#   3  error           usage error, gh/jq missing, API failure, unparseable body.
+#                      ERRORS NEVER QUARANTINE -- an unproven claim is worse than a rerun.
+#
+# Every invocation prints exactly one stdout marker as its LAST stdout line:
+#   SOLEUR_RED_ON_MAIN verdict=<v> check="<name>" main_run=<id|none> main_conclusion=<c|none>
+# with ` reason=<api|parse|missing-tool|usage|mktemp|interrupted>` appended on the error
+# path. All diagnostics go
+# to stderr so the marker is the only stdout line.
+#
+# --report (the only write path; dedupe is sentinel-keyed, mirroring main-health-monitor):
+#   * red-on-main: list open `ci/main-broken` issues, find those carrying
+#     `<!-- soleur:red-on-main check="<name>" -->` (oldest first), comment on the oldest; if
+#     none, `gh label create ci/main-broken --force 2>/dev/null || true` then file with
+#     --milestone "Post-MVP / Later" --label ci/main-broken --label meta/machinery --label
+#     type/chore. A LIST FAILURE warns and files NOTHING -- never a duplicate on a transient
+#     error (#1357 lesson: the rate-limit response is this query's own failure condition).
+#   * green-on-main: comment-and-close EVERY open issue carrying OUR sentinel for that exact
+#     check name -- never a human-filed tracker, never another check's sentinel (#7374's
+#     out-of-scope-green lesson is what the sentinel encodes).
+#   * no-evidence/error: no issue operations at all.
+#
+# `gh api` GET calls embed the query in the URL -- never `-f`/`--raw-field`, which flips the
+# request to POST and 404s the actions runs endpoints (measured 2026-09-29, PR #9233). And
+# `gh api` has no `--arg` (cli/cli#10263): two-stage `gh api URL | jq --arg` is the only
+# sanctioned shape. `gh api` also has no `-R/--repo` flag, so --repo is embedded in the path.
+set -uo pipefail
+
+readonly MARKER="SOLEUR_RED_ON_MAIN"
+
+usage() {
+  cat <<'EOF'
+usage: check-red-on-main.sh "<check-name>" --run-id <failing-run-id> [--report] [--repo owner/repo]
+       check-red-on-main.sh --self-test
+       check-red-on-main.sh --help
+
+Answers whether the check that failed in run <failing-run-id> is ALSO failing on main: scans up
+to 5 completed main-branch runs of the same workflow, newest first, for a job named EXACTLY
+<check-name> (matrix suffixes included). Skipped/absent jobs are not evidence.
+
+exit 0 green-on-main | 1 red-on-main (quarantine) | 2 no-evidence (not quarantined) | 3 error
+
+Last stdout line, on every path except --help and --self-test:
+  SOLEUR_RED_ON_MAIN verdict=<v> check="<name>" main_run=<id|none> main_conclusion=<c|none> [reason=<r>]
+
+--report files/dedupes a `ci/main-broken` tracker keyed on the sentinel
+`<!-- soleur:red-on-main check="<name>" -->` on red, and comments+closes sentinel-owned issues
+on green. Errors and no-evidence never file and never close.
+EOF
+}
+
+CHECK_OUT="-"; MAIN_RUN="none"; MAIN_CONCL="none"; REASON="none"
+
+marker() { # <verdict> ; always the LAST stdout line
+  if [[ "$1" == error ]]; then
+    printf '%s verdict=error check="%s" main_run=%s main_conclusion=%s reason=%s\n' \
+      "$MARKER" "$CHECK_OUT" "$MAIN_RUN" "$MAIN_CONCL" "$REASON"
+  else
+    printf '%s verdict=%s check="%s" main_run=%s main_conclusion=%s\n' \
+      "$MARKER" "$1" "$CHECK_OUT" "$MAIN_RUN" "$MAIN_CONCL"
+  fi
+}
+
+die3() { # <message> <reason-token>
+  printf 'check-red-on-main: ERROR: %s\n' "$1" >&2
+  REASON="$2"; marker error; exit 3
+}
+
+usage_error() {
+  printf 'check-red-on-main: %s\n' "$1" >&2
+  usage >&2
+  REASON=usage; marker error; exit 3
+}
+
+# ── the pure classifier ─────────────────────────────────────────────────────────────────────
+# job_verdict <check-name> -- reads ONE OR MORE concatenated jobs-page objects on stdin (the
+# `gh api --paginate` output shape) and prints "<red|green|none> <conclusion-or->". `none`
+# covers absent, skipped, stale, action_required, and still-running jobs alike: only a real
+# conclusion is evidence.
+job_verdict() {
+  local name="$1" pair
+  pair=$(jq -sr --arg n "$name" '
+    [ .[] | .jobs[]? | select(.name == $n) ] as $m
+    | if ($m | length) == 0 then "ABSENT -"
+      else (((($m | map(select(.status == "completed")) | .[0]) // $m[0]).status // "-")
+            + " " + (((($m | map(select(.status == "completed")) | .[0]) // $m[0]).conclusion // "-"))) end') \
+    || return 3
+  case "$pair" in
+    "completed failure"|"completed timed_out"|"completed cancelled"|"completed startup_failure") echo "red ${pair#* }" ;;
+    "completed success"|"completed neutral")                       echo "green ${pair#* }" ;;
+    *)                                                             echo "none ${pair#* }" ;;
+  esac
+}
+
+self_test() {
+  command -v jq >/dev/null 2>&1 || { echo "check-red-on-main: jq required for --self-test" >&2; exit 3; }
+  local name='deploy-script-tests (1/4)' fails=0
+  st() { # <want-verdict> <json-docs...>
+    local want="$1"; shift
+    local doc got=""
+    for doc in "$@"; do got+="$doc"$'\n'; done
+    got=$(printf '%s' "$got" | job_verdict "$name") || { echo "  self-test: job_verdict errored" >&2; fails=$((fails + 1)); return; }
+    [[ "${got%% *}" == "$want" ]] || { echo "  self-test: want $want, got '$got'" >&2; fails=$((fails + 1)); }
+  }
+  st red   '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"failure"}]}'
+  st red   '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"cancelled"}]}'
+  st red   '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"timed_out"}]}'
+  st red   '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"startup_failure"}]}'
+  st green '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"success"}]}'
+  st green '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"neutral"}]}'
+  st none  '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"skipped"}]}'
+  st none  '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"stale"}]}'
+  st none  '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"action_required"}]}'
+  st none  '{"jobs":[{"name":"deploy-script-tests (1/4)","status":"in_progress","conclusion":null}]}'
+  st none  '{"jobs":[{"name":"deploy-script-tests","status":"completed","conclusion":"failure"}]}'
+  st none  '{"jobs":[{"name":"lint","status":"completed","conclusion":"failure"}]}'
+  # two concatenated page objects (the --paginate output shape) must still find the job
+  st red   '{"total_count":41,"jobs":[{"name":"lint","status":"completed","conclusion":"success"}]}' \
+           '{"total_count":41,"jobs":[{"name":"deploy-script-tests (1/4)","status":"completed","conclusion":"failure"}]}'
+  if (( fails > 0 )); then
+    printf 'SOLEUR_RED_ON_MAIN_SELFTEST failed (%s case(s))\n' "$fails" >&2; exit 3
+  fi
+  echo "SOLEUR_RED_ON_MAIN_SELFTEST ok"
+  exit 0
+}
+
+# ── args ──────────────────────────────────────────────────────────────────────────────────────
+CHECK=""; RUN_ID=""; REPORT=0; REPO=""; SELFTEST=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --self-test) SELFTEST=1; shift ;;
+    --help|-h)   usage; exit 0 ;;
+    --run-id)
+      [[ "${2-}" =~ ^[0-9]+$ ]] || usage_error "--run-id needs a numeric workflow-run id"
+      RUN_ID="$2"; shift 2 ;;
+    --report)  REPORT=1; shift ;;
+    --repo)
+      [[ "${2-}" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || usage_error "--repo needs owner/repo"
+      REPO="$2"; shift 2 ;;
+    -*) usage_error "unknown flag $1" ;;
+    *)  [[ -z "$CHECK" ]] || usage_error "unexpected extra argument $1"; CHECK="$1"; shift ;;
+  esac
+done
+(( SELFTEST == 1 )) && self_test
+[[ -n "$CHECK" ]] || usage_error "<check-name> is required"
+# Check names are PR-author-controlled text reaching the operator's terminal, the stdout
+# marker, and (under --report) issue titles/bodies: control characters would let a crafted
+# name forge terminal escapes, split the monitor's TSV rows, or break the sentinel.
+[[ "$CHECK" != *'"'* && "$CHECK" != *'-->'* && "$CHECK" != *[[:cntrl:]]* && "$CHECK" != *$'\x7f'* ]] \
+  || usage_error "check name cannot carry a double-quote, a control character, or '-->' (sentinel/marker safety)"
+CHECK_OUT="$CHECK"
+[[ -n "$RUN_ID" ]] || usage_error "--run-id <failing-run-id> is required"
+
+for bin in gh jq; do
+  command -v "$bin" >/dev/null 2>&1 || { echo "check-red-on-main: ERROR: $bin not found on PATH" >&2; REASON="missing-tool"; marker error; exit 3; }
+done
+
+WORK="$(mktemp -d)" || { echo "check-red-on-main: ERROR: mktemp failed" >&2; REASON=mktemp; marker error; exit 3; }
+trap 'rm -rf "$WORK"' EXIT
+trap 'REASON=interrupted; marker error; exit 130' INT TERM HUP
+
+# gh api has no -R/--repo flag: --repo is embedded in the endpoint path instead.
+if [[ -n "$REPO" ]]; then RP="repos/$REPO"; REPO_ARG=(--repo "$REPO"); else RP="repos/{owner}/{repo}"; REPO_ARG=(); fi
+
+# ── resolve the workflow through the failing run ─────────────────────────────────────────────
+gh api "$RP/actions/runs/$RUN_ID" > "$WORK/run.json" 2>"$WORK/gh-err" \
+  || die3 "gh api actions/runs/$RUN_ID failed: $(head -c 200 "$WORK/gh-err" | tr '\n' ' ')" api
+jq -e 'type == "object" and (.workflow_id | type) == "number"' "$WORK/run.json" >/dev/null 2>&1 \
+  || die3 "unparseable actions/runs/$RUN_ID response (no numeric workflow_id)" parse
+WFID=$(jq -r '.workflow_id' "$WORK/run.json")
+
+# ── windowed scan of completed main runs, newest first ───────────────────────────────────────
+gh api "$RP/actions/workflows/$WFID/runs?branch=main&status=completed&per_page=5" > "$WORK/wfruns.json" 2>"$WORK/gh-err" \
+  || die3 "gh api workflows/$WFID/runs failed: $(head -c 200 "$WORK/gh-err" | tr '\n' ' ')" api
+jq -e 'type == "object" and (.workflow_runs | type) == "array"' "$WORK/wfruns.json" >/dev/null 2>&1 \
+  || die3 "unparseable workflow-runs response" parse
+IDS_RAW=$(jq -r '[.workflow_runs[:5][] | .id | select(type == "number")] | .[]' "$WORK/wfruns.json") \
+  || die3 "unparseable workflow-runs response" parse
+
+OUTCOME=""
+while IFS= read -r rid; do
+  [[ -n "$rid" ]] || continue
+  # </dev/null: the run-id herestring feeds the loop's stdin; a gh flag that ever read stdin
+  # would drain it. Same guard on the report() close loop below.
+  gh api --paginate "$RP/actions/runs/$rid/jobs?per_page=100" > "$WORK/jobs.json" 2>"$WORK/gh-err" </dev/null \
+    || die3 "gh api actions/runs/$rid/jobs failed: $(head -c 200 "$WORK/gh-err" | tr '\n' ' ')" api
+  jv=$(job_verdict "$CHECK" < "$WORK/jobs.json") \
+    || die3 "unparseable jobs response for main run $rid" parse
+  case "${jv%% *}" in
+    red|green) OUTCOME="${jv%% *}"; MAIN_RUN="$rid"; MAIN_CONCL="${jv#* }"; break ;;
+    none) ;;
+  esac
+done <<<"$IDS_RAW"
+
+case "$OUTCOME" in
+  red)   VERDICT=red-on-main;   RC=1 ;;
+  green) VERDICT=green-on-main; RC=0 ;;
+  *)     VERDICT=no-evidence;   RC=2 ;;
+esac
+
+# ── --report: sentinel-keyed issue file/dedupe/close ─────────────────────────────────────────
+report() {
+  local SENTINEL="<!-- soleur:red-on-main check=\"$CHECK\" -->"
+  local rc=0 open_json
+  # rc captured separately: `|| true` would collapse "no tracker" and "API error" into the same
+  # empty string, and the filer would file a duplicate on a transient failure (#1357 lesson).
+  # No --search: the issue LIST api is strongly consistent, while search indexes a new issue
+  # seconds-to-minutes late — two probes close together could then each file a duplicate
+  # tracker. Mirrors main-health-monitor's idiom: list the labeled issues, filter the
+  # sentinel locally.
+  open_json=$(gh issue list "${REPO_ARG[@]}" --label "ci/main-broken" --state open \
+    --json number,body --limit 100) || rc=$?
+  if [[ "$rc" -ne 0 ]] || ! jq -e 'type == "array"' <<<"$open_json" >/dev/null 2>&1; then
+    echo "check-red-on-main: could not list ci/main-broken issues (rc=$rc) -- not filing or closing anything, to avoid acting on a transient error" >&2
+    return 0
+  fi
+
+  if [[ "$VERDICT" == red-on-main ]]; then
+    # OLDEST first: gh issue list returns created-DESC, so .[0] unsorted is the NEWEST -- an
+    # older tracker would be orphaned and keep the file-new arm unreachable forever.
+    local existing
+    existing=$(jq -r --arg s "$SENTINEL" \
+      '[.[] | select(.body | type == "string" and contains($s)) | .number] | sort | .[0] // empty' \
+      <<<"$open_json" 2>/dev/null) || existing=""
+    if [[ -n "$existing" ]]; then
+      # >/dev/null: gh prints the comment URL on stdout — the marker is the only stdout line.
+      gh issue comment "$existing" "${REPO_ARG[@]}" --body \
+        "Still red on main: check \`$CHECK\` concluded $MAIN_CONCL on main run $MAIN_RUN. (probe run: $RUN_ID)" \
+        >/dev/null || echo "check-red-on-main: could not comment on #$existing" >&2
+      echo "check-red-on-main: commented on existing sentinel tracker #$existing" >&2
+      return 0
+    fi
+    gh label create "ci/main-broken" --force "${REPO_ARG[@]}" >/dev/null 2>&1 || true
+    local url
+    url=$(gh issue create "${REPO_ARG[@]}" \
+      --title "Red on main: $CHECK" \
+      --body "$(printf '%s\n' \
+        "$SENTINEL" \
+        "" \
+        "Check \`$CHECK\` is failing on main." \
+        "" \
+        "- Newest exercising main run: $MAIN_RUN (conclusion: $MAIN_CONCL)" \
+        "- Observed failing on PR-side run: $RUN_ID" \
+        "" \
+        "Filed by check-red-on-main.sh --report: this check is quarantined for PR rerun/fix" \
+        "decisions while it is red on main. This tracker is auto-closed when the check goes" \
+        "green on main again — to verify/close, re-run" \
+        "\`check-red-on-main.sh \"$CHECK\" --run-id <any run id of this workflow> --report\`;" \
+        "a green verdict closes this issue.")" \
+      --label "ci/main-broken" --label "meta/machinery" --label "type/chore" \
+      --milestone "Post-MVP / Later" 2>/dev/null) || url=""
+    if [[ -n "$url" ]]; then
+      echo "check-red-on-main: filed tracker $url" >&2
+    else
+      echo "check-red-on-main: issue create failed -- the red-on-main verdict stands but no tracker was filed" >&2
+    fi
+    return 0
+  fi
+
+  # green-on-main: comment-and-close ONLY issues carrying OUR sentinel for this check name --
+  # every one of them, never a human-filed or other-sentinel tracker.
+  local mine n
+  mine=$(jq -r --arg s "$SENTINEL" \
+    '[.[] | select(.body | type == "string" and contains($s)) | .number] | sort | .[]' \
+    <<<"$open_json" 2>/dev/null) || mine=""
+  while IFS= read -r n; do
+    [[ -n "$n" ]] || continue
+    gh issue close "$n" "${REPO_ARG[@]}" --comment \
+      "Check \`$CHECK\` is green on main again (run $MAIN_RUN, conclusion $MAIN_CONCL). Auto-closing." \
+      >/dev/null </dev/null || echo "check-red-on-main: could not close #$n" >&2
+    echo "check-red-on-main: closed sentinel tracker #$n -- main is green again" >&2
+  done <<<"$mine"
+  return 0
+}
+
+if (( REPORT == 1 )) && [[ "$VERDICT" == red-on-main || "$VERDICT" == green-on-main ]]; then
+  report
+fi
+
+marker "$VERDICT"
+exit "$RC"