sno-ai/sno-station-skills / skills/J-peer-review-and-audit/peer-review/skill
peer-review
VerifiedAdversarial review and fix loop for code, specs, plans, and migration manifests.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 32.7 KB |
| agents/openai.yaml | config | 216 B |
| assets/adversarial-plan-review.prompt.md | markdown | 11.0 KB |
| assets/adversarial-review.prompt.md | markdown | 12.0 KB |
| assets/adversarial-test-review.prompt.md | markdown | 3.5 KB |
| references/code-layers.md | markdown | 5.4 KB |
| references/doc-layers.md | markdown | 5.5 KB |
| references/python-advanced-patterns.md | markdown | 7.8 KB |
| references/python-standards.md | markdown | 8.3 KB |
| references/ts-standards.md | markdown | 7.1 KB |
| scripts/lib/sno-model.sh | script | 1.5 KB |
| scripts/review-backfill.shexecutable | script | 4.7 KB |
| scripts/review-findings.shexecutable | script | 11.7 KB |
| scripts/review-receipt.shexecutable | script | 5.3 KB |
| scripts/run-adversarial-review.shexecutable | script | 57.6 KB |
| scripts/selftest/cursor-process-group.t | other | 2.0 KB |
| scripts/selftest/run-cross-vendor.sh | script | 14.5 KB |
| scripts/selftest/run-model-settings.shexecutable | script | 5.1 KB |
| scripts/selftest/run-selftest.shexecutable | script | 39.2 KB |
scripts/run-adversarial-review.sh
View on GitHub#!/usr/bin/env bash
# run-adversarial-review.sh — run the peer-review adversarial-review prompt in
# a fresh headless reviewer session, with target contents supplied by stdin/file.
#
# Why this script exists:
# - Inlining file contents means the reviewer never needs filesystem access,
# so its sandbox cannot block a read of a path outside its working directory.
# - One stable command means the calling agent does not have to reconstruct a
# fragile heredoc inline. A single `bash <script> <files>` call is reproducible.
# - Reviewer independence: the review runs in its own new session that has
# none of the caller's conversation. Only an answer from another vendor
# counts; exhausted candidates leave a refusal, never a same-vendor review.
#
# Usage:
# run-adversarial-review.sh <file1> [<file2> ...]
#
# Environment overrides (all optional):
# FOCUS — focus area string to steer the reviewer
# XDG_CONFIG_HOME — settings root (default: $HOME/.config); sno/models.toml
# selects role reviewer (Codex) or reviewer_claude (Claude).
# Unset/empty role: no model flag.
# REVIEW_CALLER — claude-code | codex | hermes | openclaw | cursor.
# Otherwise detect seat, ancestors, then session markers.
# REVIEW_AUTHOR_MODEL — current model for a multi-vendor caller without a seat.
# REVIEW_REVIEWER — cursor: explicitly select an isolated Cursor reviewer.
# REVIEW_AUTHOR — the harness that wrote the work under
# review (default: REVIEW_CALLER). Only labels the uploaded
# review.run event; it never changes the reviewer choice.
# CODEX_EFFORT — Codex reasoning effort (default: high)
# REVIEW_KIND — prompt selection: code (default) | plan/spec/doc
# (plan-specific adversarial prompt: premise attack,
# probe-evidence classification, coverage statement)
# STALL_SECS — kill+retry after this many seconds with no stdout,
# stderr, or final-message activity (default: 600).
# Reasoning summaries are streamed so a live codex keeps
# this counter reset; only a truly wedged process trips
# it. Do not lower this below the longest silent stretch
# a healthy review can have.
# TIMEOUT_SECS — hard per-attempt wall-clock cap (default: 3600).
# Concurrent reviews share one account's rate budget and
# run several times slower than a solo review, so this
# cap has to clear the slowest parallel wave, not the
# solo one.
# MAX_RETRIES — retries after a stall/timeout/nonzero-exit/empty
# final response, on top of the first attempt (default: 2)
# POLL_SECS — watchdog poll interval (default: 5)
# PROGRESS_SECS — progress heartbeat interval (default: 30)
# BACKOFF_BASE_SECS — retry backoff multiplier (default: 5)
# PAYLOAD_LIMIT — inlined-file byte budget before auto-batching kicks
# in (default: 92160 = 90KiB)
# MAX_FILES_PER_WAVE — file-count budget before auto-batching kicks in
# (default: 8)
# MAX_PARALLEL — how many reviews may run at once across every caller
# on this machine (default: 8). Over the cap this exits
# 9 immediately instead of waiting for a free slot.
#
# Reliability: a reviewer CLI can hang — stderr stops growing right after it
# echoes the inlined prompt, stdout stays at 0 bytes, and the process lingers
# for many minutes before exiting with nothing. The hang can be intermittent.
# This script:
# (a) watches all output files for growth and kills+retries on a stall or
# a hard per-attempt timeout;
# (b) also retries on nonzero exit or empty final response;
# (c) auto-splits large payloads into waves so no single codex call is
# enormous, and merges the per-wave reports into one report on stdout.
# In plan/spec/doc review mode, the FIRST target file (the artifact under
# review; evidence files follow) is pinned into every wave so grounding
# never loses sight of it.
#
# Notes:
# - The script does NOT pass file paths to the reviewer. It sees only the
# inlined text under "=== FILE: <path> ===" markers in stdin.
# - --skip-git-repo-check is set so review works from any cwd.
# - Exit codes: 2 cross review unavailable / author unknown / prompt unreadable, 3 no files given,
# 4 a target file is unreadable, 5 unknown REVIEW_KIND/caller,
# 7 merged report could not be written (wave captures kept),
# 8 invalid reliability override, 9 concurrency cap reached (nothing ran;
# safe to retry later — the caller must not block waiting on a slot),
# 10 same-scope review cap reached, 11 journey mode without CHARTER/FENCE.
#
# Accounting. Every invocation writes a `start` line to the ledger
# at dispatch and one terminal line — `end` (it finished, well or badly) or
# `refused` (nothing ran) — when it stops. A start with no terminal line is a
# run that was killed, and is the only trace SIGKILL can leave; the receipt
# script reports exactly those as "not actually covered". Reports are kept under
# REVIEW_ARCHIVE_DIR (default ~/.local/state/codex-reviews/<date>/) rather than
# /tmp, and the end line names the file.
#
# scripts/review-receipt.sh [--since <date|today|all>] [--journey <id>] [--check]
set -uo pipefail
# Deliberately no `set -e`: this script inspects nonzero exits from codex
# (stall/timeout/failure) to drive its own retry logic, so a nonzero status
# from a single attempt must not abort the whole script.
SKILL_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
# REVIEW_KIND is validated here but its prompt is resolved AFTER the target list
# is known, because an all-test target set selects `test` on its own (below).
REVIEW_KIND_EXPLICIT=0
[[ -n "${REVIEW_KIND:-}" ]] && REVIEW_KIND_EXPLICIT=1
REVIEW_KIND="${REVIEW_KIND:-code}"
case "$REVIEW_KIND" in
plan|spec|doc|code|test) : ;;
*) echo "error: unknown REVIEW_KIND '$REVIEW_KIND' (use code|plan|test)" >&2; exit 5 ;;
esac
agent_from_command() {
local word
local -a words
read -r -a words <<< "$1"
for word in "${words[@]}"; do
case "${word##*/}" in
claude) printf claude-code; return ;;
codex|hermes|openclaw) printf '%s' "${word##*/}"; return ;;
openclaw-tui) printf openclaw; return ;;
cursor-agent) printf cursor; return ;;
esac
done
return 1
}
REVIEW_CALLER="${REVIEW_CALLER:-}"
# A Cursor started from another agent's shell inherits that agent's ancestors and markers.
if [[ -z "$REVIEW_CALLER" && -n "${CURSOR_AGENT:-}" ]]; then
REVIEW_CALLER=cursor
fi
if [[ -z "$REVIEW_CALLER" && -n "${SNO_REACH_ADDR:-}" ]]; then
runtime=$(python3 - "${SNO_REACH_STATE_ROOT:-$HOME/.local/state/sno-reach}/$SNO_REACH_ADDR/seat.json" <<'PY'
import json, sys
try:
with open(sys.argv[1]) as f:
print(json.load(f).get("runtime", ""))
except (OSError, ValueError):
pass
PY
)
REVIEW_CALLER=$(agent_from_command "$runtime")
fi
if [[ -z "$REVIEW_CALLER" ]]; then
ancestor=$PPID
while [[ "$ancestor" =~ ^[0-9]+$ && "$ancestor" -gt 1 ]]; do
read -r parent comm argv < <(ps -p "$ancestor" -o ppid= -o comm= -o args= 2>/dev/null) || break
REVIEW_CALLER=$(agent_from_command "$comm $argv")
[[ -z "$REVIEW_CALLER" ]] || break
[[ "$parent" != "$ancestor" ]] || break
ancestor=$parent
done
fi
if [[ -z "$REVIEW_CALLER" ]]; then
if [[ -n "${CODEX_THREAD_ID:-}" ]]; then REVIEW_CALLER=codex
elif [[ -n "${CLAUDECODE:-}" ]]; then REVIEW_CALLER=claude-code
else REVIEW_CALLER=claude-code
fi
fi
case "$REVIEW_CALLER" in
claude-code|codex|hermes|openclaw|cursor) : ;;
*) echo "error: REVIEW_CALLER must be claude-code, codex, hermes, openclaw or cursor" >&2; exit 5 ;;
esac
case "${REVIEW_REVIEWER:-}" in
''|cursor) : ;;
*) echo "error: REVIEW_REVIEWER must be cursor or unset" >&2; exit 5 ;;
esac
REVIEW_AUTHOR="${REVIEW_AUTHOR:-$REVIEW_CALLER}"
REVIEWER="" REVIEWER_MODEL="" REVIEWER_PROVIDER="" REVIEWER_VENDOR="" REVIEWER_SESSION=""
if [[ $# -eq 0 ]]; then
echo "usage: $(basename "$0") <file1> [<file2> ...]" >&2
exit 3
fi
FILES=("$@")
N=${#FILES[@]}
for f in "${FILES[@]}"; do
if [[ ! -r "$f" ]]; then
echo "error: target file not readable: $f" >&2
exit 4
fi
done
# ---------------------------------------------------------------------------
# Test files are a different review, not a smaller one.
#
# The code prompt hunts data loss, security holes and silently wrong results.
# Pointed at a test file it produces findings about the TEST's own robustness
# and edge cases — work nobody asked for on an artifact that exists only to
# prove one thing about something else. The same-scope cap keys on the whole
# target set, so re-batching can bypass it.
#
# So `test` gets its own prompt, a cap of one, and a per-FILE counter that
# re-batching cannot reset.
# ---------------------------------------------------------------------------
is_test_file() { # $1 = path -> 0 when it is test material
local p="$1"
[[ "$p" == */tests/* || "$p" == tests/* ]] && return 0
[[ "$p" == */test/* || "$p" == test/* ]] && return 0
[[ "$p" == */spec/* || "$p" == spec/* ]] && return 0
[[ "$p" == */__tests__/* ]] && return 0
case "${p##*/}" in
*.t|*.test.*|*.spec.*|test_*.py|*_test.py|*-e2e.sh|*-e2e.*.sh) return 0 ;;
esac
return 1
}
TEST_FILES=() PROD_FILES=()
for f in "${FILES[@]}"; do
if is_test_file "$f"; then TEST_FILES+=("$f"); else PROD_FILES+=("$f"); fi
done
# Auto-select. A caller who never sets REVIEW_KIND still gets the right review;
# one who sets it explicitly keeps what they asked for, and the deliberate
# override is logged so it stays visible in the ledger rather than silent.
# `log` is defined further down, so this early block writes to stderr directly.
if [[ ${#TEST_FILES[@]} -eq $N && "$REVIEW_KIND" == "code" ]]; then
if [[ "$REVIEW_KIND_EXPLICIT" -eq 1 ]]; then
printf '%s\n' "[run-adversarial-review] every target is a test file, but REVIEW_KIND=code was set explicitly — honouring it." >&2
else
REVIEW_KIND="test"
printf '%s\n' "[run-adversarial-review] every target is a test file -> REVIEW_KIND=test (purpose-only, cap 1)." >&2
fi
fi
# A mixed batch is the quiet version of the same waste: the test files inherit
# the production prompt AND ride the production scope cap, so they get reviewed
# up to three times with the wrong questions. They are moved out of this review
# and named, with the exact command for their own single pass. They are NOT run
# automatically — doing that from an exit handler would start a fresh review on
# a Ctrl-C — and the deferral is written to the ledger.
DEFERRED_TEST_FILES=()
if [[ "$REVIEW_KIND" == "code" && ${#TEST_FILES[@]} -gt 0 && ${#PROD_FILES[@]} -gt 0 ]]; then
DEFERRED_TEST_FILES=("${TEST_FILES[@]}")
FILES=("${PROD_FILES[@]}")
N=${#FILES[@]}
printf '%s\n' "[run-adversarial-review] mixed batch: ${#DEFERRED_TEST_FILES[@]} test file(s) moved OUT of this code review." >&2
printf '%s\n' " A test file needs one purpose-only pass, not up to three production rounds. Run:" >&2
printf '%s\n' " REVIEW_KIND=test bash $0 ${DEFERRED_TEST_FILES[*]}" >&2
printf '%s\n' " Recorded as deferred in the ledger." >&2
fi
DOC_MODE=0
case "$REVIEW_KIND" in
plan|spec|doc) PROMPT_FILE="$SKILL_DIR/assets/adversarial-plan-review.prompt.md"; DOC_MODE=1 ;;
test) PROMPT_FILE="$SKILL_DIR/assets/adversarial-test-review.prompt.md" ;;
code) PROMPT_FILE="$SKILL_DIR/assets/adversarial-review.prompt.md" ;;
esac
if [[ ! -r "$PROMPT_FILE" ]]; then
echo "error: prompt template not readable at $PROMPT_FILE" >&2
exit 2
fi
source "$SKILL_DIR/scripts/lib/sno-model.sh" || exit 2
CODEX_MODEL="$(sno_model reviewer)" || exit 2
CLAUDE_MODEL="$(sno_model reviewer_claude)" || exit 2
CODEX_EFFORT="${CODEX_EFFORT:-high}"
FOCUS_TEXT="${FOCUS:-none}"
STALL_SECS="${STALL_SECS:-600}"
TIMEOUT_SECS="${TIMEOUT_SECS:-3600}"
MAX_RETRIES="${MAX_RETRIES:-2}"
PAYLOAD_LIMIT="${PAYLOAD_LIMIT:-92160}"
WAVE_SIZE_CHOSEN=0
[[ -n "${MAX_FILES_PER_WAVE:-}" ]] && WAVE_SIZE_CHOSEN=1
MAX_FILES_PER_WAVE="${MAX_FILES_PER_WAVE:-8}"
POLL_SECS="${POLL_SECS:-5}"
PROGRESS_SECS="${PROGRESS_SECS:-30}"
BACKOFF_BASE_SECS="${BACKOFF_BASE_SECS:-5}"
MAX_PARALLEL="${MAX_PARALLEL:-8}"
log() { printf '%s\n' "$*" >&2; }
send_event() {
local event="$1" status; shift
if ! command -v sno >/dev/null 2>&1; then
log "sno: not found; $event event not recorded"
return 0
fi
if timeout 60 sno observe append "$event" "$@" >/dev/null 2>&1; then
:
else
status=$?
log "sno observe append $event failed (exit $status); event not recorded"
fi
return 0
}
bytesize() { wc -c < "$1" 2>/dev/null | tr -d ' '; }
require_uint() {
local name="$1" value="$2" allow_zero="${3:-0}"
if [[ ! "$value" =~ ^[0-9]+$ ]] || { [[ "$allow_zero" -eq 0 ]] && [[ "$value" -eq 0 ]]; }; then
log "error: $name must be $([[ "$allow_zero" -eq 1 ]] && printf 'a non-negative' || printf 'a positive') integer"
exit 8
fi
}
require_uint STALL_SECS "$STALL_SECS"
require_uint TIMEOUT_SECS "$TIMEOUT_SECS"
require_uint MAX_RETRIES "$MAX_RETRIES" 1
require_uint PAYLOAD_LIMIT "$PAYLOAD_LIMIT"
require_uint MAX_FILES_PER_WAVE "$MAX_FILES_PER_WAVE"
require_uint POLL_SECS "$POLL_SECS"
require_uint PROGRESS_SECS "$PROGRESS_SECS"
require_uint BACKOFF_BASE_SECS "$BACKOFF_BASE_SECS" 1
require_uint MAX_PARALLEL "$MAX_PARALLEL"
# Probe evidence — plan/spec/doc reviews only. The prompt forbids the reviewer
# shell tools, so with no PROBE-RESULTS file it is sitting a closed-book exam:
# internal contradictions and unenforced guarantees it catches, but "the document
# claims A, the code actually does B" is structurally invisible to it. The channel
# already exists and is documented as authoritative ground truth; being optional
# is precisely why it gets skipped. Warn, and record it — a review conducted
# without evidence has to stay identifiable after the fact.
PROBE_PRESENT=false
if [[ "$DOC_MODE" -eq 1 ]]; then
for f in "${FILES[@]}"; do
case "$(basename -- "$f")" in
*PROBE-RESULTS*) PROBE_PRESENT=true; break ;;
esac
done
if [[ "$PROBE_PRESENT" != true ]]; then
log "[run-adversarial-review] WARNING: no PROBE-RESULTS file among the targets."
log " This ${REVIEW_KIND} review can check the document against itself but NOT against"
log " reality — every empirical claim in it will come back unverified, not refuted."
log " Run the checks the review depends on, write the raw output to a PROBE-RESULTS"
log " file, and pass it as an extra target. Recorded as probe=false."
fi
fi
# ---------------------------------------------------------------------------
# HARD CAP + invocation stats.
# Same-scope review invocations are capped regardless of what they return:
# code=3 (2 fix rounds + 1 confirmation), plan/spec/doc=5. At the cap:
# findings that are NOT verified blockers of the current deliverable go to tech
# debt (recorded, later); verified blockers are reported to the user.
# REVIEW_CAP_OVERRIDE=<reason> lifts a cap; the reason is recorded on the stats line.
#
# Caps count only passes inside REVIEW_CAP_WINDOW_HOURS (default 24).
# Counting all history would eventually prevent reviews of changed artifacts.
# REVIEW_CAP_WINDOW_HOURS=0 counts all history.
STATS_FILE="${STATS_FILE:-$HOME/.local/state/codex-review-stats.jsonl}"
mkdir -p "$(dirname "$STATS_FILE")"; touch "$STATS_FILE"
REVIEW_JOURNEY="${REVIEW_JOURNEY:-adhoc}"
case "$REVIEW_KIND" in
code) _default_cap=3 ;;
test) _default_cap=1 ;; # one pass, never a round loop
*) _default_cap=5 ;; # plan/spec/doc: five judgment passes per window
esac
REVIEW_CAP="${REVIEW_CAP:-$_default_cap}"
require_uint REVIEW_CAP "$REVIEW_CAP"
SCOPE_KEY="$(printf '%s\n' "${FILES[@]}" | LC_ALL=C sort | sha1sum | cut -c1-12)"
SCOPE_ID="${REVIEW_JOURNEY}:${SCOPE_KEY}"
REVIEW_CAP_WINDOW_HOURS="${REVIEW_CAP_WINDOW_HOURS:-24}"
require_uint REVIEW_CAP_WINDOW_HOURS "$REVIEW_CAP_WINDOW_HOURS" 1 # 0 = count all history
CAP_WINDOW_CUTOFF=0
CAP_WINDOW_ACTIVE=0
# iso_epoch <YYYY-MM-DDTHH:MM:SS+HH:MM>: epoch seconds. GNU date reads it with -d;
# BSD date (macOS) has no -d and reads it with -j -f once the offset loses its colon.
iso_epoch() {
local t="$1"
date -d "$t" +%s 2>/dev/null && return 0
if [[ "$t" =~ ^(.*[+-][0-9]{2}):([0-9]{2})$ ]]; then t="${BASH_REMATCH[1]}${BASH_REMATCH[2]}"; fi
date -j -f '%Y-%m-%dT%H:%M:%S%z' "$t" +%s 2>/dev/null
}
if (( REVIEW_CAP_WINDOW_HOURS > 0 )); then
# iso_epoch must read the ledger's timestamps. Without it the filter would
# drop every line and no cap would ever trip, so prove it gives the known
# answer before relying on it and otherwise fall back to counting all
# history — fail closed, not open.
if [[ "$(iso_epoch "2026-01-01T00:00:00+00:00")" == 1767225600 ]]; then
CAP_WINDOW_ACTIVE=1
CAP_WINDOW_CUTOFF=$(( $(date +%s) - REVIEW_CAP_WINDOW_HOURS * 3600 ))
else
log "[run-adversarial-review] date cannot read ISO 8601 times; cap window disabled, counting all history"
fi
fi
# Keeps only ledger lines stamped inside the cap window. Fed pre-filtered lines
# (one scope, one journey, or one file), so the per-line `date` call runs a
# handful of times, not once per ledger row. A line with no `ts` predates the
# stamp and cannot be shown to be recent, so it is treated as outside.
within_cap_window() {
local line ts epoch
if (( CAP_WINDOW_ACTIVE == 0 )); then cat; return 0; fi
while IFS= read -r line; do
[[ "$line" == *'"ts":"'* ]] || continue
ts="${line#*\"ts\":\"}"
ts="${ts%%\"*}"
epoch="$(iso_epoch "$ts")" || continue
(( epoch >= CAP_WINDOW_CUTOFF )) && printf '%s\n' "$line"
done
return 0
}
# ---------------------------------------------------------------------------
# Ledger: a start line at dispatch, one terminal line at the end.
#
# Without a start line, a killed review could leave neither a report nor a
# record. The caller could not distinguish "found nothing" from "never ran".
#
# The fix is a start line, not a better exit trap: SIGKILL cannot be trapped, so
# a trap-only fix would miss killed runs. A start with no
# matching terminal line IS the "not actually covered" row, computable after the
# fact and immune to how the process died.
#
# Line shapes (one JSON object per line, appended with a single printf so that
# parallel reviewers cannot interleave a partial write):
# event=start dispatch happened. No `outcome` key.
# event=refused nothing ran: cap reached, journey contract unmet, no slot.
# No `outcome` key.
# event=end the review finished, well or badly. Carries `outcome`.
# Only `end` lines carry `outcome`, which is
# what the round counter above keys on.
# ---------------------------------------------------------------------------
LEDGER_TERMINAL_WRITTEN=0
LAST_FAILURE_KIND=""
# One id per invocation, carried by all three line shapes. Pairing on scope+round
# is ambiguous exactly where it matters: a killed round-3 run writes no end line,
# so the next attempt is round 3 again and a receipt cannot tell the two apart.
RUN_ID="$(date +%s)-$$"
json_str() { # $1 -> a JSON string literal, quotes and backslashes escaped
local s="$1"
s="${s//\\/\\\\}"
s="${s//\"/\\\"}"
printf '"%s"' "$s"
}
json_arr() { # $@ -> a JSON array of strings
local out="[" first=1 v
for v in "$@"; do
[[ "$first" -eq 1 ]] || out+=","
out+="$(json_str "$v")"
first=0
done
printf '%s]' "$out"
}
ledger_write() { # $1 = the complete JSON object, minus the trailing newline
printf '%s\n' "$1" >> "$STATS_FILE"
}
# Reports are kept in durable storage, named so a
# ledger line and its report can be paired without searching.
# An explicit REVIEW_OUTPUT_FILE from the caller still wins; existing callers
# pass one and must keep getting exactly that path.
REVIEW_ARCHIVE_DIR="${REVIEW_ARCHIVE_DIR:-$HOME/.local/state/codex-reviews}"
archive_path() {
local day; day="$(date +%F)"
if mkdir -p "$REVIEW_ARCHIVE_DIR/$day" 2>/dev/null; then
printf '%s/%s/%s-%s-%s.md' "$REVIEW_ARCHIVE_DIR" "$day" "$RUN_ID" "$SCOPE_KEY" "$REVIEW_KIND"
else
# An unwritable archive must not cost the review; fall back and say so.
log "[run-adversarial-review] cannot write ${REVIEW_ARCHIVE_DIR} — this report will NOT be kept"
mktemp -t codex-review.XXXXXX.md
fi
}
record_start() {
ledger_write "$(printf '{"ts":%s,"event":"start","run":%s,"scope":%s,"journey":%s,"kind":%s,"round":%d,"cap":%d,"files":%d,"targets":%s,"probe":%s,"model":%s,"effort":%s,"pid":%d}' \
"$(json_str "$(date -Iseconds)")" "$(json_str "$RUN_ID")" "$(json_str "$SCOPE_ID")" "$(json_str "$REVIEW_JOURNEY")" \
"$(json_str "$REVIEW_KIND")" "$ROUND_N" "$REVIEW_CAP" "$N" "$(json_arr "${FILES[@]}")" "$PROBE_PRESENT" \
"$(json_str "$CODEX_MODEL")" "$(json_str "$CODEX_EFFORT")" "$$")"
}
record_refused() { # $1 = reason tag, $2 = human detail
LEDGER_TERMINAL_WRITTEN=1
ledger_write "$(printf '{"ts":%s,"event":"refused","run":%s,"scope":%s,"journey":%s,"kind":%s,"round":%d,"cap":%d,"files":%d,"targets":%s,"reason":%s,"detail":%s}' \
"$(json_str "$(date -Iseconds)")" "$(json_str "$RUN_ID")" "$(json_str "$SCOPE_ID")" "$(json_str "$REVIEW_JOURNEY")" \
"$(json_str "$REVIEW_KIND")" "${ROUND_N:-0}" "$REVIEW_CAP" "$N" "$(json_arr "${FILES[@]}")" \
"$(json_str "$1")" "$(json_str "$2")")"
}
# Round counting must see COMPLETED reviews only. Each invocation now writes a
# `start` line as well as an end line, and a refused invocation writes a
# `refused` line — counting raw scope hits would make every round count double
# and trip the cap during what is really round 2. Only end lines carry an
# `outcome` key, so `"outcome":"` counts completed reviews.
PRIOR_ROUNDS=$( { grep -F "\"scope\":\"${SCOPE_ID}\"" "$STATS_FILE" 2>/dev/null || true; } \
| grep -F '"outcome":"' | within_cap_window | grep -c . || true )
ROUND_N=$(( PRIOR_ROUNDS + 1 ))
if (( ROUND_N > REVIEW_CAP )) && [[ -z "${REVIEW_CAP_OVERRIDE:-}" ]]; then
log "[run-adversarial-review] HARD CAP: scope ${SCOPE_ID} already reviewed ${PRIOR_ROUNDS}x (cap ${REVIEW_CAP} for ${REVIEW_KIND})."
log "Continue the authorized task: diagnose and fix in-scope defects, then run affected checks."
log "This limit ends repeated review, not repair work; no new approval is needed for routine fixes."
record_refused cap "already reviewed ${PRIOR_ROUNDS}x, cap ${REVIEW_CAP}"
exit 10
fi
if [[ -n "${REVIEW_CAP_OVERRIDE:-}" ]]; then
log "[run-adversarial-review] cap override reason: ${REVIEW_CAP_OVERRIDE}"
fi
# Plan/spec/doc are one judgment family. The same artifact must not escape the
# planning cap by changing either the review alias or one companion target.
# Count completed reviews by journey and by file across all three aliases, up to
# REVIEW_CAP passes per window. Beyond that the
# legal next step is deterministic validation and implementation, unless an
# override reason is supplied through REVIEW_CAP_OVERRIDE.
if [[ "$REVIEW_KIND" == "plan" || "$REVIEW_KIND" == "spec" || "$REVIEW_KIND" == "doc" ]] && [[ -z "${REVIEW_CAP_OVERRIDE:-}" ]]; then
plan_kinds=$( { grep -E '"kind":"(plan|spec|doc)"' "$STATS_FILE" 2>/dev/null || true; } \
| grep -F '"outcome":"' | within_cap_window || true )
if [[ "$REVIEW_JOURNEY" != "adhoc" ]]; then
journey_seen=$(printf '%s\n' "$plan_kinds" \
| grep -F "\"journey\":\"${REVIEW_JOURNEY}\"" | grep -c . || true)
if (( journey_seen >= REVIEW_CAP )); then
log "[run-adversarial-review] PLANNING JOURNEY CAP: ${REVIEW_JOURNEY} already used ${journey_seen} judgment passes (cap ${REVIEW_CAP})."
log " Fix only current-slice blockers, run deterministic validation once, then implement."
record_refused plan-journey-cap "journey already used ${journey_seen} plan/spec/doc passes"
exit 10
fi
fi
already=()
for f in "${FILES[@]}"; do
seen=$(printf '%s\n' "$plan_kinds" | grep -cF "$(json_str "$f")" || true)
(( seen >= REVIEW_CAP )) && already+=("$f")
done
if (( ${#already[@]} > 0 )); then
log "[run-adversarial-review] PLAN FILE CAP: these artifacts already used ${REVIEW_CAP} judgment passes in the window:"
for f in "${already[@]}"; do log " $f"; done
log " Changing REVIEW_KIND or the companion target set does not create a new round."
log " Fix current-slice defects and verify them directly, then continue implementation; do not park the task."
record_refused plan-file-cap "already reviewed ${REVIEW_CAP}x: ${already[*]}"
exit 10
fi
fi
# Per-FILE cap for test material. The scope cap above keys on the whole target
# set, so dropping or adding one unrelated file mints a fresh scope and restarts
# the counter, which would let one test file be reviewed without limit. This
# counter keys on the path, so re-batching cannot reset it. Production files are deliberately untouched: their scope cap
# works and re-reviewing a source file after a fix is the intended loop.
if [[ "$REVIEW_KIND" == "test" && -z "${REVIEW_CAP_OVERRIDE:-}" ]]; then
already=()
for f in "${FILES[@]}"; do
seen=$( { grep -F "\"kind\":\"test\"" "$STATS_FILE" 2>/dev/null || true; } \
| grep -F '"outcome":"' | grep -F "$(json_str "$f")" | within_cap_window \
| grep -c . || true )
(( seen > 0 )) && already+=("$f")
done
if (( ${#already[@]} > 0 )); then
log "[run-adversarial-review] TEST FILE ALREADY REVIEWED — one purpose pass per test file, and these have had theirs:"
for f in "${already[@]}"; do log " $f"; done
log " A test file is proof of one thing about something else; re-reviewing it"
log " polishes the proof instead of the product. If the test's PURPOSE genuinely"
log " changed, repair and verify that test directly; a review refusal does not end the task."
record_refused test-file-cap "already reviewed: ${already[*]}"
exit 10
fi
fi
REVIEW_START_EPOCH=$(date +%s)
TOTAL_LINES=$(cat -- "${FILES[@]}" 2>/dev/null | wc -l | tr -d ' ')
# Context contract (advisory injection; enforced only when REVIEW_JOURNEY is set):
# REVIEW_JOURNEY = a label grouping the reviews of one piece of work;
# CHARTER = one-line task statement or a file path saying what the change is for;
# FENCE = path of a file listing the paths the change may touch;
# CONTEXT_FILE = a file describing the deployment context (trust model, platform,
# format invariants) that severity is judged against.
# A labelled (journey) review without CHARTER and FENCE is refused; ad-hoc calls
# proceed without them (the cap still applies).
CHARTER="${CHARTER:-}"; FENCE="${FENCE:-}"; CONTEXT_FILE="${CONTEXT_FILE:-}"
if [[ "$REVIEW_JOURNEY" != "adhoc" ]] && { [[ -z "$CHARTER" ]] || [[ -z "$FENCE" ]]; }; then
log "error: journey-mode review (REVIEW_JOURNEY=${REVIEW_JOURNEY}) requires CHARTER and FENCE"
record_refused contract "journey mode without CHARTER and FENCE"
exit 11
fi
record_stats() { # $1=outcome $2=report-file(optional)
local outcome="$1" report="${2:-}" dur verdict="" nFix="" nDebt="" nCtx="" nH="" nM=""
# Written-once: the interrupt handler and the four success/failure paths can
# both reach here, and a second end line would inflate the round counter that
# keys on `"outcome":"` and trip the hard cap a round early.
[[ "$LEDGER_TERMINAL_WRITTEN" -eq 1 ]] && return 0
LEDGER_TERMINAL_WRITTEN=1
dur=$(( $(date +%s) - REVIEW_START_EPOCH ))
if [[ -n "$report" && -r "$report" ]]; then
verdict="$(grep -m1 -oE 'Verdict: [a-z-]+' "$report" | cut -d' ' -f2)"
nFix=$(grep -cE '\[fix-now\]' "$report" || true)
nDebt=$(grep -cE '\[debt\]' "$report" || true)
nCtx=$(grep -cE '\[out-of-context\]' "$report" || true)
nH=$(grep -cE '^\- \[(high|critical)' "$report" || true)
nM=$(grep -cE '^\- \[medium' "$report" || true)
fi
# `failure` names WHY a run ended badly, which the outcome alone never did:
# empty (codex exited clean and wrote nothing), watchdog (stalled or hit the
# hard timeout and was killed), exit:<n> (codex itself failed), interrupted
# (this wrapper was signalled). Empty on success.
ledger_write "$(printf '{"ts":%s,"event":"end","run":%s,"scope":%s,"journey":%s,"kind":%s,"round":%d,"cap":%d,"files":%d,"targets":%s,"lines":%s,"probe":%s,"duration_s":%d,"waves":%s,"report":%s,"outcome":%s,"failure":%s,"verdict":%s,"fix_now":%s,"debt":%s,"out_of_context":%s,"high":%s,"medium":%s,"override":%s,"caller":%s,"reviewer":%s,"reviewer_vendor":%s}' \
"$(json_str "$(date -Iseconds)")" "$(json_str "$RUN_ID")" "$(json_str "$SCOPE_ID")" "$(json_str "$REVIEW_JOURNEY")" \
"$(json_str "$REVIEW_KIND")" "$ROUND_N" "$REVIEW_CAP" "$N" "$(json_arr "${FILES[@]}")" \
"${TOTAL_LINES:-0}" "$PROBE_PRESENT" "$dur" "${NUM_WAVES:-1}" "$(json_str "$report")" "$(json_str "$outcome")" \
"$(json_str "${LAST_FAILURE_KIND:-}")" "$(json_str "${verdict:-unknown}")" \
"${nFix:-null}" "${nDebt:-null}" "${nCtx:-null}" "${nH:-null}" "${nM:-null}" \
"$(json_str "${REVIEW_CAP_OVERRIDE:-}")" "$(json_str "$REVIEW_CALLER")" \
"$(json_str "$REVIEWER")" "$(json_str "$REVIEWER_VENDOR")")"
# Findings go somewhere durable, keyed by reviewed file, with a status column.
# Never allowed to fail the review: the
# report is already written and on stdout by this point.
if [[ "$outcome" == "success" && -n "$report" && -r "$report" ]]; then
local rf="$SKILL_DIR/scripts/review-findings.sh"
if [[ -r "$rf" ]]; then
bash "$rf" record "$report" --run "$RUN_ID" --scope "$SCOPE_ID" \
--kind "$REVIEW_KIND" 2>&1 >/dev/null | head -3 >&2 || true
fi
local p1 p2 p3 empty=true reviewer_harness="$REVIEWER" author_harness="$REVIEW_AUTHOR" project
read -r p1 p2 p3 < <(awk '
{
line = tolower($0)
sub(/^[[:space:]]+/, "", line)
if (line !~ /^-[[:space:]]+\[(critical|high|medium|low)\]/) next
if (line ~ /^-[[:space:]]+\[[^]]+\][[:space:]]*\[(debt|out-of-context)\]/) next
if (line !~ /[[:space:]]+\(.+\)[[:space:]]*$/) next
if (line ~ /^-[[:space:]]+\[(critical|high)\]/) p1++
else if (line ~ /^-[[:space:]]+\[medium\]/) p2++
else p3++
}
END { print p1+0, p2+0, p3+0 }
' "$report")
(( p1 + p2 + p3 == 0 )) || empty=false
[[ "$author_harness" != claude ]] || author_harness=claude-code
project="$(git rev-parse --show-toplevel 2>/dev/null)" || project="$PWD"
send_event review.run "--agent=$REVIEW_CALLER" "--project=$project" \
"--author_harness=$author_harness" "--reviewer_harness=$reviewer_harness" \
"--findings_p1=$p1" "--findings_p2=$p2" "--findings_p3=$p3" \
"--empty=$empty" "--duration_ms=$((dur * 1000))"
fi
}
normalize_vendor() {
case "$1" in
openai|openai-codex|codex|chatgpt) printf openai ;;
anthropic|claude) printf anthropic ;;
local:*) printf '%s' "$1" ;;
local*) printf 'local:%s' "$1" ;;
*) printf '%s' "$1" ;;
esac
}
cross_review_unavailable() {
local message="cross review was not possible: no reviewer on another vendor answered"
log "$message"
if [[ "$1" == refused ]]; then
record_refused no-other-vendor "$message"
else
record_stats failed ""
fi
}
PICK_ARGS=(subscription-quota-check --pick review --from "$REVIEW_CALLER")
if [[ -n "${SNO_REACH_ADDR:-}" ]]; then
PICK_ARGS+=(--seat "$SNO_REACH_ADDR")
elif [[ -n "${REVIEW_AUTHOR_MODEL:-}" ]]; then
PICK_ARGS+=(--model "$REVIEW_AUTHOR_MODEL")
elif [[ "$REVIEW_CALLER" != claude-code && "$REVIEW_CALLER" != codex ]]; then
log "error: author's model is unknown for $REVIEW_CALLER; set REVIEW_AUTHOR_MODEL or use a Reach seat; no review runs"
record_refused current-model-unknown "author's model is unknown for $REVIEW_CALLER"
exit 2
fi
if ! PICK_JSON=$(timeout 60 sno "${PICK_ARGS[@]}" --json); then
log "error: reviewer pick failed for $REVIEW_CALLER; no review runs"
cross_review_unavailable refused
exit 2
fi
if ! jq -e '.ok == true' <<< "$PICK_JSON" >/dev/null 2>&1; then
if [[ "$(jq -r '.reason // empty' <<< "$PICK_JSON" 2>/dev/null)" == current-model-unknown ]]; then
log "error: author's model is unknown for $REVIEW_CALLER; set REVIEW_AUTHOR_MODEL or repair the Reach seat; no review runs"
record_refused current-model-unknown "author's model is unknown for $REVIEW_CALLER"
else
cross_review_unavailable refused
fi
exit 2
fi
case "$REVIEW_CALLER" in
claude-code) AUTHOR_VENDOR=anthropic ;;
codex) AUTHOR_VENDOR=openai ;;
*) AUTHOR_VENDOR=$(jq -r '.from.vendor // empty' <<< "$PICK_JSON") ;;
esac
if [[ -z "$AUTHOR_VENDOR" ]]; then
log "error: author's model is unknown for $REVIEW_CALLER; no review runs"
record_refused current-model-unknown "author's model is unknown for $REVIEW_CALLER"
exit 2
fi
if [[ "${REVIEW_REVIEWER:-}" == cursor ]]; then
PICK_JSON=$(jq '.candidates |= map(select(.agent == "cursor"))' <<< "$PICK_JSON")
elif [[ "$REVIEW_CALLER" == cursor ]]; then
preferred=claude-code
if jq -e --arg vendor "$AUTHOR_VENDOR" 'any(.candidates[]; .agent == "codex" and .vendor != $vendor)' <<< "$PICK_JSON" >/dev/null &&
command -v codex >/dev/null 2>&1 && timeout 60 codex login status </dev/null >/dev/null 2>&1; then
preferred=codex
fi
PICK_JSON=$(jq --arg preferred "$preferred" '.candidates |= map(select(.agent == $preferred))' <<< "$PICK_JSON")
fi
if ! jq -e '.candidates | length > 0' <<< "$PICK_JSON" >/dev/null 2>&1; then
cross_review_unavailable refused
exit 2
fi
# ---------------------------------------------------------------------------
# Concurrency slot — fail fast, never queue.
#
# Concurrent reviews share one account's token-rate budget, so past a handful
# of them every request slows down and none of them finish sooner. This claims
# one of MAX_PARALLEL advisory locks and gives up IMMEDIATELY if they are all
# held: blocking here would pin a caller's process doing nothing, which is the
# exact failure this cap exists to prevent. The caller decides when to retry.
#
# A slot is a directory: mkdir is atomic on every filesystem this runs on, so
# two reviewers racing for the last slot cannot both win. flock is not used —
# it needs bash 4's `exec {fd}>` and a flock(1) binary, neither of which exists
# on macOS, where the cap would then silently do nothing.
#
# A reviewer killed with SIGKILL cannot clean up after itself, so each slot
# records its owner's pid and any slot whose owner is gone is reclaimed on the
# next scan. That keeps a crashed run from permanently burning a slot.
# ---------------------------------------------------------------------------
SLOT_DIR="${TMPDIR:-/tmp}/codex-review-slots"
SLOT_HELD=""
release_slot() {
if [[ -n "$SLOT_HELD" ]]; then
rm -rf "$SLOT_HELD"
SLOT_HELD=""
fi
}
take_slot() {
local slot="$1" label="$2"
mkdir "$slot" 2>/dev/null || return 1
printf '%s' "$$" > "$slot/pid"
SLOT_HELD="$slot"
log "[run-adversarial-review] claimed concurrency slot ${label}"
return 0
}
claim_slot() {
mkdir -p "$SLOT_DIR" 2>/dev/null || return 0
local i slot owner
for (( i=1; i<=MAX_PARALLEL; i++ )); do
slot="$SLOT_DIR/slot-$i"
take_slot "$slot" "${i}/${MAX_PARALLEL}" && return 0
owner=$(cat "$slot/pid" 2>/dev/null)
if [[ -n "$owner" ]] && ! kill -0 "$owner" 2>/dev/null; then
rm -rf "$slot"
take_slot "$slot" "${i}/${MAX_PARALLEL} (reclaimed from dead pid ${owner})" && return 0
fi
done
return 1
}
if ! claim_slot; then
log "error: all ${MAX_PARALLEL} concurrent review slots are busy — refusing to queue."
log " Retry this file later, or raise MAX_PARALLEL if the account can take the load."
record_refused no_slot "all ${MAX_PARALLEL} concurrency slots held"
exit 9
fi
trap release_slot EXIT
# From here on a codex process may actually be dispatched, so the run becomes
# something that has to be accounted for. Written after the slot is claimed:
# a run that never got a slot ran nothing and is recorded as `refused` above.
record_start
# Deferred test files are recorded as their own ledger row. It is written here
# rather than at the split so that a run refused before dispatch does not leave
# a deferral nobody caused.
if (( ${#DEFERRED_TEST_FILES[@]} > 0 )); then
ledger_write "$(printf '{"ts":%s,"event":"deferred","run":%s,"scope":%s,"journey":%s,"kind":%s,"files":%d,"targets":%s,"reason":%s}' \
"$(json_str "$(date -Iseconds)")" "$(json_str "$RUN_ID")" "$(json_str "$SCOPE_ID")" \
"$(json_str "$REVIEW_JOURNEY")" "$(json_str "test")" "${#DEFERRED_TEST_FILES[@]}" \
"$(json_arr "${DEFERRED_TEST_FILES[@]}")" "$(json_str "moved out of a code review; needs one REVIEW_KIND=test pass")")"
fi
terminate_tree() {
local pid="$1" signal="$2" child
while read -r child; do
[[ -n "$child" ]] && terminate_tree "$child" "$signal"
done < <(pgrep -P "$pid" 2>/dev/null)
kill "-$signal" "$pid" 2>/dev/null || true
}
kill_tree() {
local pid="$1" i
terminate_tree "$pid" TERM
for i in 1 2 3; do
kill -0 "$pid" 2>/dev/null || return 0
sleep 1
done
terminate_tree "$pid" KILL
}
ACTIVE_PID=""
stop_active() {
if [[ -n "$ACTIVE_PID" ]] && kill -0 "$ACTIVE_PID" 2>/dev/null; then
log "[run-adversarial-review] interrupted — killing $REVIEWER process tree (pid $ACTIVE_PID)"
kill_tree "$ACTIVE_PID"
fi
}
# Best-effort terminal line when this wrapper is signalled — a caller's deadline
# or a Ctrl-C. It is deliberately NOT the mechanism the accounting relies on:
# SIGKILL cannot be trapped, so the start line above is what makes an
# unaccounted-for run detectable no matter how the process died.
trap 'stop_active; LAST_FAILURE_KIND=interrupted; record_stats interrupted ""; exit 130' INT TERM HUP
activity_size() {
local total=0 size file
for file in "$@"; do
size=$(bytesize "$file"); size=${size:-0}
total=$(( total + size ))
done
printf '%s' "$total"
}
# run_reviewer_once PROMPT_FILE STDOUT_FILE STDERR_FILE OUTPUT_LAST_MSG_FILE
# Runs one reviewer attempt with a liveness watchdog on all output growth plus a
# hard overall timeout. Returns the CLI's exit status, or 124 if the watchdog
# killed it (stall or timeout).
run_reviewer_once() {
local prompt_file="$1" stdout_file="$2" stderr_file="$3" last_msg_file="$4"
: > "$stdout_file"
: > "$stderr_file"
: > "$last_msg_file"
# Built as one array (rather than splicing the possibly-empty MODEL_ARGS
# into the middle of the command) because expanding an empty array under
# `set -u` throws "unbound variable" on bash 3.2 (macOS's default /bin/bash).
local codex_args=(exec --skip-git-repo-check --sandbox read-only)
if [[ -n "$CODEX_MODEL" ]]; then
codex_args+=(--model "$CODEX_MODEL")
fi
# Streaming reasoning summaries are the ONLY liveness signal this watchdog
# has: without them codex writes its header, then nothing at all until the
# final message lands. A growth-based stall check against a silent process kills
# healthy runs.
codex_args+=(
-c "model_reasoning_effort=$CODEX_EFFORT"
-c "model_reasoning_summary=detailed"
--output-last-message "$last_msg_file" -
)
local claude_args=(-p)
if [[ -n "$CLAUDE_MODEL" ]]; then
claude_args+=(--model "$CLAUDE_MODEL")
fi
claude_args+=(
--effort medium --tools ''
--disable-slash-commands --strict-mcp-config --no-session-persistence
--output-format text
)
log "[run-adversarial-review] caller=$REVIEW_CALLER reviewer=$REVIEWER model=$REVIEWER_MODEL provider=$REVIEWER_PROVIDER"
REVIEWER_SESSION=""
# env -u: the reviewer starts a new session and never inherits the caller's.
if [[ "$REVIEWER" == claude-code ]]; then
env -u CLAUDECODE -u CODEX_THREAD_ID claude "${claude_args[@]}" \
< "$prompt_file" > "$last_msg_file" 2> "$stderr_file" &
elif [[ "$REVIEWER" == cursor ]]; then
# A throwaway home holding only the login and the install, and an empty folder: none of the user's or the
# project's Cursor hooks fire and no memory is captured. --trust: a never-opened folder otherwise exits
# "Workspace Trust Required"; ask mode is read-only.
cursor_tmp="$(mktemp -d)"
mkdir -p "$cursor_tmp/home/.local" "$cursor_tmp/cwd"
ln -s "$HOME/.local/share" "$cursor_tmp/home/.local/share"
if [[ "$(uname -s)" == Darwin ]]; then
cursor_library="$cursor_tmp/home"/Library
mkdir -p "$cursor_library"; ln -s "$HOME/Library/Keychains" "$cursor_library/Keychains"
else
mkdir -p "$cursor_tmp/home/.config/cursor"
cp -- "$HOME/.config/cursor/auth.json" "$cursor_tmp/home/.config/cursor/" 2>/dev/null ||
log "[run-adversarial-review] $HOME/.config/cursor/auth.json is missing; Cursor CLI not logged in"
fi
# Its own process group: cursor-agent leaves a language server running after it exits (observed).
set -m
( cd -- "$cursor_tmp/cwd" && exec env -u CLAUDECODE -u CODEX_THREAD_ID -u CURSOR_AGENT HOME="$cursor_tmp/home" \
cursor-agent -p --trust --mode ask --output-format json ) < "$prompt_file" > "$stdout_file" 2> "$stderr_file" &
cursor_pid=$!
set +m
elif [[ "$REVIEWER" == codex ]]; then
env -u CLAUDECODE -u CODEX_THREAD_ID codex "${codex_args[@]}" \
< "$prompt_file" > "$stdout_file" 2> "$stderr_file" &
elif [[ "$REVIEWER" == hermes ]]; then
local hermes_args=(chat --query-file "$prompt_file" --oneshot -Q --ignore-user-config --ignore-rules)
[[ -z "$REVIEWER_MODEL" ]] || hermes_args+=(-m "$REVIEWER_MODEL")
[[ -z "$REVIEWER_PROVIDER" ]] || hermes_args+=(--provider "$REVIEWER_PROVIDER")
env -u CLAUDECODE -u CODEX_THREAD_ID hermes "${hermes_args[@]}" \
> "$stdout_file" 2> "$stderr_file" &
elif [[ "$REVIEWER" == openclaw ]]; then
REVIEWER_SESSION="agent:main:explicit:sno-oneshot-${RUN_ID}-${RANDOM}"
env -u CLAUDECODE -u CODEX_THREAD_ID openclaw agent --agent main \
--session-id "${REVIEWER_SESSION##*:}" --model "$REVIEWER_PROVIDER/$REVIEWER_MODEL" \
--message-file "$prompt_file" --json > "$stdout_file" 2> "$stderr_file" &
fi
ACTIVE_PID=$!
local start now elapsed quiet last_size cur_size last_growth next_progress status
start=$(date +%s); last_growth=$start; last_size=0; next_progress=$PROGRESS_SECS
while kill -0 "$ACTIVE_PID" 2>/dev/null; do
sleep "$POLL_SECS"
now=$(date +%s)
cur_size=$(activity_size "$stdout_file" "$stderr_file" "$last_msg_file")
if [[ "$cur_size" -gt "$last_size" ]]; then
last_size=$cur_size
last_growth=$now
fi
elapsed=$(( now - start ))
quiet=$(( now - last_growth ))
if (( elapsed >= next_progress )); then
log "[run-adversarial-review] running ${elapsed}s, quiet ${quiet}s, output ${cur_size} bytes"
next_progress=$(( next_progress + PROGRESS_SECS ))
fi
if (( elapsed >= TIMEOUT_SECS )); then
log "[run-adversarial-review] hard timeout after ${elapsed}s — killing $REVIEWER (pid $ACTIVE_PID)"
kill_tree "$ACTIVE_PID"
wait "$ACTIVE_PID" 2>/dev/null
ACTIVE_PID=""
return 124
fi
if (( quiet >= STALL_SECS )); then
log "[run-adversarial-review] stalled ${quiet}s with no output activity — killing $REVIEWER (pid $ACTIVE_PID)"
kill_tree "$ACTIVE_PID"
wait "$ACTIVE_PID" 2>/dev/null
ACTIVE_PID=""
return 124
fi
done
wait "$ACTIVE_PID"
status=$?
ACTIVE_PID=""
if [[ "$status" -eq 0 ]]; then
case "$REVIEWER" in
hermes)
REVIEWER_SESSION=$(sed -n 's/^[[:space:]]*session_id: \([^[:space:]]*\).*$/\1/p' "$stdout_file" "$stderr_file" | tail -1)
sed '/^[[:space:]]*session_id: /d' "$stdout_file" > "$last_msg_file" ;;
openclaw)
jq -r '(.result.payloads // .payloads // []) | map(.text // empty) | join("\n")' \
"$stdout_file" > "$last_msg_file" || return 1 ;;
esac
fi
if [[ "$REVIEWER" == cursor ]]; then
kill -KILL -- "-$cursor_pid" 2>/dev/null || true
rm -rf -- "$cursor_tmp"
if grep -q 'keychain is locked' "$stderr_file" "$stdout_file"; then
log "[run-adversarial-review] Cursor CLI login unreadable (keychain locked); run it from the desktop session"
fi
# The JSON answer's `result` is the review; `is_error` is a failed run, not a review.
[[ "$status" -ne 0 ]] || jq -er 'if .is_error then error("cursor-agent reported an error") else .result end' \
"$stdout_file" > "$last_msg_file" || status=1
fi
return "$status"
}
# run_with_retries PROMPT_FILE STDOUT_FILE STDERR_FILE OUTPUT_LAST_MSG_FILE LABEL
# Retries fixed-vendor CLIs up to MAX_RETRIES times on stall/timeout/nonzero
# exit/empty final response. Returns 0 on success.
run_with_retries() {
local prompt_file="$1" stdout_file="$2" stderr_file="$3" last_msg_file="$4" label="$5"
local attempt=1 max_attempts=$(( MAX_RETRIES + 1 )) status
[[ "$REVIEWER" == codex || "$REVIEWER" == claude-code ]] || max_attempts=1
while (( attempt <= max_attempts )); do
log "[run-adversarial-review] ${label}: attempt ${attempt}/${max_attempts}…"
run_reviewer_once "$prompt_file" "$stdout_file" "$stderr_file" "$last_msg_file"
status=$?
if [[ $status -eq 0 ]] && grep -q '[^[:space:]]' "$last_msg_file"; then
log "[run-adversarial-review] ${label}: attempt ${attempt}/${max_attempts} succeeded"
LAST_FAILURE_KIND=""
return 0
fi
# Name the failure so the ledger can distinguish the three that look
# identical from outside: codex exited clean and wrote nothing, the
# watchdog killed a stalled or overlong run, or codex itself failed.
if [[ $status -eq 124 ]]; then
LAST_FAILURE_KIND="watchdog"
elif [[ $status -eq 0 ]]; then
LAST_FAILURE_KIND="empty"
else
LAST_FAILURE_KIND="exit:${status}"
fi
log "[run-adversarial-review] ${label}: attempt ${attempt}/${max_attempts} failed (${LAST_FAILURE_KIND}, exit=${status}, final_bytes=$(bytesize "$last_msg_file"))"
if (( attempt < max_attempts )); then
local backoff=$(( attempt * BACKOFF_BASE_SECS ))
log "[run-adversarial-review] ${label}: retrying after ${backoff}s backoff…"
sleep "$backoff"
fi
attempt=$(( attempt + 1 ))
done
return 1
}
run_with_candidates() {
local provider candidate
while IFS= read -r candidate; do
IFS=$'\x1f' read -r REVIEWER REVIEWER_MODEL REVIEWER_PROVIDER REVIEWER_VENDOR <<< "$candidate"
provider=""
case "$REVIEWER" in
codex) REVIEWER_VENDOR=openai; REVIEWER_MODEL=$CODEX_MODEL ;;
claude-code) REVIEWER_VENDOR=anthropic; REVIEWER_MODEL=$CLAUDE_MODEL ;;
hermes|openclaw) : ;;
cursor) [[ "${REVIEW_REVIEWER:-}" == cursor ]] || { log "[run-adversarial-review] skipped agent=cursor model=$REVIEWER_MODEL reason=cursor-not-isolated"; continue; } ;;
*) log "[run-adversarial-review] skipped agent=$REVIEWER model=$REVIEWER_MODEL reason=unavailable"; continue ;;
esac
[[ "$REVIEWER_VENDOR" != "$AUTHOR_VENDOR" ]] || continue
if run_with_retries "$@"; then
provider=$REVIEWER_PROVIDER
case "$REVIEWER" in
codex) provider=openai ;;
claude-code) provider=anthropic ;;
hermes)
provider=""
[[ -z "$REVIEWER_SESSION" ]] || provider=$(timeout 60 sno rotate-agent-answer-provider \
--agent hermes --session "$REVIEWER_SESSION") || provider="" ;;
openclaw)
provider=$(timeout 60 sno rotate-agent-answer-provider --agent openclaw --session-key "$REVIEWER_SESSION") || provider="" ;;
esac
REVIEWER_VENDOR=$(normalize_vendor "$provider")
if [[ -n "$REVIEWER_VENDOR" && "$REVIEWER_VENDOR" != "$AUTHOR_VENDOR" ]]; then
return 0
fi
LAST_FAILURE_KIND=answer-vendor-unknown
[[ -z "$REVIEWER_VENDOR" ]] || LAST_FAILURE_KIND=same-vendor-answer
fi
log "[run-adversarial-review] discarded agent=$REVIEWER model=$REVIEWER_MODEL provider=${provider:-unknown} requested_provider=$REVIEWER_PROVIDER session=$REVIEWER_SESSION reason=$LAST_FAILURE_KIND"
: > "$4"
done < <(jq -r '.candidates[] | [.agent, (.model // ""), (.provider // ""), (.vendor // "")] | join("\u001f")' <<< "$PICK_JSON")
return 1
}
# build_prompt PROMPT_OUT_FILE WAVE_NOTE FILE_INDICES...
# Assembles the prompt template + inlined target files + focus line into
# PROMPT_OUT_FILE, mirroring the original single-shot inlining format.
build_prompt() {
local out_file="$1" wave_note="$2"; shift 2
local idx f
{
printf '%s\n' '[sno-oneshot] Station one-shot run, not a user session.'
sed 's/You are Codex performing/You are performing/; s/# Codex Adversarial/# Adversarial/' "$PROMPT_FILE"
# Context contract: severity must be judged
# against this; a severity cap is legal ONLY when it cites an entry here.
if [[ -n "$CHARTER" || -n "$FENCE" || -n "$CONTEXT_FILE" ]]; then
printf '\n<context_contract>\n'
if [[ -n "$CHARTER" ]]; then
if [[ -r "$CHARTER" ]]; then printf 'Charter (what this change is FOR):\n'; cat -- "$CHARTER";
else printf 'Charter (what this change is FOR): %s\n' "$CHARTER"; fi
fi
if [[ -n "$FENCE" && -r "$FENCE" ]]; then
printf '\nScope fence (paths this change may touch):\n'; cat -- "$FENCE"
fi
if [[ -n "$CONTEXT_FILE" && -r "$CONTEXT_FILE" ]]; then
printf '\nDeployment context (trust model / platform / format invariants):\n'
cat -- "$CONTEXT_FILE"
fi
printf '</context_contract>\n'
fi
if [[ -n "$wave_note" ]]; then
printf '\n%s\n' "$wave_note"
fi
printf '\n'
for idx in "$@"; do
f="${FILES[$idx]}"
printf '\n=== FILE: %s ===\n' "$f"
cat -- "$f"
done
printf '\nUser focus: %s\n' "$FOCUS_TEXT"
} > "$out_file"
}
# ---------------------------------------------------------------------------
# Decide single-wave vs batched, based on total payload size / file count.
# ---------------------------------------------------------------------------
TOTAL_BYTES=0
declare -a SIZES
for f in "${FILES[@]}"; do
sz=$(bytesize "$f"); sz=${sz:-0}
SIZES+=("$sz")
TOTAL_BYTES=$(( TOTAL_BYTES + sz ))
done
# Wave size is a judgement, so it is announced rather than applied silently.
# The trade is real in both directions and only the caller knows which side it
# needs: a LARGER wave puts more files in front of one reviewer at once, which
# is the only way cross-file contradictions become visible. A SMALLER wave buys
# depth per file and less dilution, which is what a
# security or correctness pass over dense source wants. The 8 here is a default,
# not a finding; set MAX_FILES_PER_WAVE deliberately when either side matters.
if (( WAVE_SIZE_CHOSEN == 1 )); then
log "[run-adversarial-review] wave size ${MAX_FILES_PER_WAVE} file(s) — chosen by the caller."
else
log "[run-adversarial-review] wave size ${MAX_FILES_PER_WAVE} file(s) — DEFAULT, nobody chose it."
log " Larger keeps cross-file contradictions visible in one pass; smaller buys depth."
log " Set MAX_FILES_PER_WAVE when either matters."
fi
BATCH=0
if (( TOTAL_BYTES > PAYLOAD_LIMIT || N > MAX_FILES_PER_WAVE )); then
BATCH=1
fi
if [[ "$BATCH" -eq 0 ]]; then
# ---- Single-wave path (backward compatible shape) ----------------------
PROMPT_TMP="$(mktemp -t codex-review-prompt.XXXXXX)"
STDOUT_TMP="$(mktemp -t codex-review-stdout.XXXXXX)"
STDERR_TMP="$(mktemp -t codex-review-stderr.XXXXXX)"
REVIEW_OUTPUT_FILE="${REVIEW_OUTPUT_FILE:-$(archive_path)}"
all_idx=()
for (( i=0; i<N; i++ )); do all_idx+=("$i"); done
build_prompt "$PROMPT_TMP" "" "${all_idx[@]}"
if run_with_candidates "$PROMPT_TMP" "$STDOUT_TMP" "$STDERR_TMP" "$REVIEW_OUTPUT_FILE" "review"; then
cat -- "$REVIEW_OUTPUT_FILE"
printf '\n[run-adversarial-review] final review also written to: %s\n' "$REVIEW_OUTPUT_FILE" >&2
record_stats success "$REVIEW_OUTPUT_FILE"
rm -f "$PROMPT_TMP" "$STDOUT_TMP" "$STDERR_TMP"
exit 0
else
cross_review_unavailable end
log "[run-adversarial-review] candidates exhausted — see stdout/stderr captures for the last attempt:"
log " stdout: $STDOUT_TMP"
log " stderr: $STDERR_TMP"
log " final: $REVIEW_OUTPUT_FILE"
log " prompt: $PROMPT_TMP"
exit 2
fi
fi
# ---- Batched path --------------------------------------------------------
TARGET_IDX=-1
if [[ "$DOC_MODE" -eq 1 && "$N" -gt 1 ]]; then
TARGET_IDX=0
fi
if [[ "$TARGET_IDX" -ge 0 ]]; then
BUDGET_BYTES=$(( PAYLOAD_LIMIT - SIZES[TARGET_IDX] ))
BUDGET_FILES=$(( MAX_FILES_PER_WAVE - 1 ))
POOL=()
for (( i=0; i<N; i++ )); do
[[ "$i" -eq "$TARGET_IDX" ]] && continue
POOL+=("$i")
done
else
BUDGET_BYTES=$PAYLOAD_LIMIT
BUDGET_FILES=$MAX_FILES_PER_WAVE
POOL=()
for (( i=0; i<N; i++ )); do POOL+=("$i"); done
fi
(( BUDGET_BYTES <= 0 )) && BUDGET_BYTES=$PAYLOAD_LIMIT
(( BUDGET_FILES <= 0 )) && BUDGET_FILES=1
# WAVES: each element is a space-separated list of file indices for that
# wave (pinned target index already included when applicable).
declare -a WAVES
CUR=() ; CUR_BYTES=0 ; CUR_COUNT=0
flush_wave() {
[[ "$CUR_COUNT" -eq 0 ]] && return 0
local wave_idx=("${CUR[@]}")
if [[ "$TARGET_IDX" -ge 0 ]]; then
wave_idx=("$TARGET_IDX" "${CUR[@]}")
fi
WAVES+=("${wave_idx[*]}")
CUR=() ; CUR_BYTES=0 ; CUR_COUNT=0
}
for idx in "${POOL[@]}"; do
fsize=${SIZES[$idx]}
if [[ "$CUR_COUNT" -gt 0 ]] && (( CUR_BYTES + fsize > BUDGET_BYTES || CUR_COUNT + 1 > BUDGET_FILES )); then
flush_wave
fi
CUR+=("$idx")
CUR_BYTES=$(( CUR_BYTES + fsize ))
CUR_COUNT=$(( CUR_COUNT + 1 ))
done
flush_wave
if [[ ${#WAVES[@]} -eq 0 && "$TARGET_IDX" -ge 0 ]]; then
# Pool was empty (a single, oversized target file) — the target still
# needs its own wave.
WAVES+=("$TARGET_IDX")
fi
NUM_WAVES=${#WAVES[@]}
log "[run-adversarial-review] payload ${TOTAL_BYTES} bytes / ${N} files exceeds batching threshold — splitting into ${NUM_WAVES} wave(s)"
WORKDIR="$(mktemp -d -t codex-review-batch.XXXXXX)"
WAVE_REPORTS=()
ANY_FAILED=0
for (( w=0; w<NUM_WAVES; w++ )); do
wave_num=$(( w + 1 ))
# shellcheck disable=SC2206 # WAVES[w] is a deliberately word-split index list
wave_idx=(${WAVES[$w]})
wave_files=()
for idx in "${wave_idx[@]}"; do wave_files+=("${FILES[$idx]}"); done
prompt_tmp="$WORKDIR/wave-${wave_num}.prompt"
stdout_tmp="$WORKDIR/wave-${wave_num}.stdout"
stderr_tmp="$WORKDIR/wave-${wave_num}.stderr"
lastmsg_tmp="$WORKDIR/wave-${wave_num}.lastmsg.md"
wave_note=""
if [[ "$NUM_WAVES" -gt 1 ]]; then
wave_note="This is wave ${wave_num}/${NUM_WAVES} of a batched review; the same target may repeat across waves for grounding, and findings will be merged with the other waves after this one."
fi
build_prompt "$prompt_tmp" "$wave_note" "${wave_idx[@]}"
if run_with_candidates "$prompt_tmp" "$stdout_tmp" "$stderr_tmp" "$lastmsg_tmp" "wave ${wave_num}/${NUM_WAVES} (${wave_files[*]})"; then
WAVE_REPORTS+=("$lastmsg_tmp")
else
log "[run-adversarial-review] wave ${wave_num}/${NUM_WAVES} exhausted candidates — files: ${wave_files[*]}"
ANY_FAILED=1
break
fi
done
if [[ "$ANY_FAILED" -eq 1 ]]; then
cross_review_unavailable end
log "[run-adversarial-review] batched review aborted — intermediate files kept at: $WORKDIR"
exit 2
fi
for (( w=0; w<NUM_WAVES; w++ )); do
wave_num=$(( w + 1 ))
printf '## Wave %d/%d\n\n' "$wave_num" "$NUM_WAVES"
cat -- "${WAVE_REPORTS[$w]}"
printf '\n'
done
MERGED_REPORT="${REVIEW_OUTPUT_FILE:-$(archive_path)}"
cat -- "${WAVE_REPORTS[@]}" > "$MERGED_REPORT" 2>/dev/null || true
# Every wave produced a report, but if the merge itself could not be written the
# findings are gone — recording that as success is exactly the silent pass this
# accounting exists to stop.
if [[ ! -s "$MERGED_REPORT" ]]; then
LAST_FAILURE_KIND="report-not-written"
record_stats failed ""
log "[run-adversarial-review] ${NUM_WAVES} wave(s) succeeded but the merged report could not be"
log " written to ${MERGED_REPORT} — the findings are NOT recorded. Wave captures: ${WORKDIR}"
exit 7
fi
record_stats success "$MERGED_REPORT"
printf '[run-adversarial-review] merged review written to: %s\n' "$MERGED_REPORT" >&2
rm -rf "$WORKDIR"
printf '[run-adversarial-review] batched review complete (%d waves merged)\n' "$NUM_WAVES" >&2
exit 0
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |