@toolu/opencode 6.8.0

package/plugins/pr-babysit/scripts/lib/normalize.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# normalize.sh — the jq vocabulary shared by collect-pr.sh and reduce-state.sh.
+#
+# Sourced. Every shape rule lives here so the collector, the reducer and the
+# tests read one definition of "CI reviewer", "check state" and "thread
+# comment". Programs are functions that print jq text (not variables) so a
+# sourced-only lib stays shellcheck-clean without exporting large strings into
+# every child process's environment.
+
+# CI-reviewer login set: REST (`user.login`) keeps the `[bot]` suffix, GraphQL
+# (`author.login`) drops it. Exact membership — never a `[bot]` substring test,
+# which misreads the GraphQL form as human.
+pb_ci_reviewers_json() { printf '%s' '["github-actions","github-actions[bot]","claude","claude[bot]"]'; }
+
+# pb_jq_defs -> jq `def`s to prepend to any program.
+pb_jq_defs() {
+  cat <<EOF
+def ci_reviewers: $(pb_ci_reviewers_json);
+def is_ci_reviewer: . as \$l | (ci_reviewers | index(\$l)) != null;
+def check_state:
+  if .__typename == "StatusContext" then
+    (if .state == "SUCCESS" then "pass"
+     elif (.state == "PENDING" or .state == "EXPECTED") then "pending"
+     else "fail" end)
+  else
+    (if .status != "COMPLETED" then "pending"
+     elif (.conclusion == "SUCCESS" or .conclusion == "NEUTRAL" or .conclusion == "SKIPPED") then "pass"
+     else "fail" end)
+  end;
+def check_name: (.name // .context // "unknown");
+def check_url: (.detailsUrl // .targetUrl // null);
+def ci_status:
+  (map(check_state)) as \$s
+  | if (\$s | length) == 0 then "pending"
+    elif (\$s | index("fail")) != null then "fail"
+    elif (\$s | index("pending")) != null then "pending"
+    else "pass" end;
+def thread_comment: {id, databaseId, body, author: (.author.login // null), authorType: (.author.__typename // null), createdAt, url};
+EOF
+}
+
+# Merge `gh api graphql --paginate --slurp` reviewThreads pages (array of page
+# objects) into the snapshot thread shape.
+pb_jq_threads_from_pages() {
+  pb_jq_defs
+  cat <<'EOF'
+[.[].data.repository.pullRequest.reviewThreads.nodes[]]
+| map({id, isResolved, isOutdated, path, line,
+       comments: (.comments.nodes | map(thread_comment)),
+       commentsHasNextPage: .comments.pageInfo.hasNextPage,
+       commentsEndCursor: .comments.pageInfo.endCursor})
+EOF
+}
+
+# Merge the per-thread `node(id:)` comment pages (array of page objects).
+pb_jq_thread_comments_from_pages() {
+  pb_jq_defs
+  printf '%s\n' '[.[].data.node.comments.nodes[]] | map(thread_comment)'
+}
+
+# Flatten `gh api --paginate --slurp` REST pages (array of arrays).
+pb_jq_rest_items() { printf '%s\n' '[.[][]]'; }
+
+pb_jq_issue_comment() {
+  printf '%s\n' '{id, body, author: (.user.login // null), authorType: (.user.type // null), createdAt: .created_at, updatedAt: .updated_at, url: .html_url}'
+}
+
+pb_jq_review() {
+  printf '%s\n' '{id, state, body, author: (.user.login // null), authorType: (.user.type // null), submittedAt: .submitted_at, url: .html_url, commitId: .commit_id}'
+}
+
+# Fields requested from `gh pr view --json`.
+pb_pr_view_fields() {
+  printf '%s' 'number,title,url,author,state,baseRefName,headRefName,headRefOid,statusCheckRollup,mergeable,reviewDecision'
+}
+
+# GraphQL documents. Both declare $endCursor so `gh api graphql --paginate`
+# drives the cursor; $pageSize keeps pagination testable on real PRs.
+pb_gql_threads() {
+  cat <<'EOF'
+query($owner:String!,$repo:String!,$number:Int!,$pageSize:Int!,$endCursor:String){
+  repository(owner:$owner,name:$repo){ pullRequest(number:$number){
+    reviewThreads(first:$pageSize,after:$endCursor){
+      pageInfo{hasNextPage endCursor}
+      nodes{ id isResolved isOutdated path line
+        comments(first:$pageSize){ pageInfo{hasNextPage endCursor}
+          nodes{ id databaseId body author{login __typename} createdAt url } } } } } } }
+EOF
+}
+
+pb_gql_thread_comments() {
+  cat <<'EOF'
+query($id:ID!,$pageSize:Int!,$endCursor:String){
+  node(id:$id){ ... on PullRequestReviewThread {
+    comments(first:$pageSize,after:$endCursor){ pageInfo{hasNextPage endCursor}
+      nodes{ id databaseId body author{login __typename} createdAt url } } } } }
+EOF
+}

package/plugins/pr-babysit/scripts/lib/state.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# state.sh — load and update one slot's state file for the write-side scripts.
+#
+# Sourced after common.sh and lock.sh. The write side (reply-thread.sh,
+# resolve-thread.sh, record.sh) always: takes the slot lock, validates the
+# state, performs its action, and records the outcome atomically. This file
+# holds the shared load/update so each script carries only its own action.
+
+# pb_state_load STATE_FILE — validate (version 2) and export the slot
+# identity: PB_STATE_REPO, PB_STATE_NUMBER, PB_STATE_HEAD. Exits through
+# pb_fail on a missing or malformed file.
+pb_state_load() {
+  local state_file="$1"
+  [ -f "$state_file" ] || pb_fail state_malformed "state file not found: $state_file (run babysit-tick.sh first)" '{"source":"state"}'
+  pb_json_valid "$state_file" || pb_fail state_malformed "state file is not valid JSON: $state_file" '{"source":"state"}'
+  jq -e '.version == 2 and (.repo | type == "string") and (.number | type == "number")' "$state_file" >/dev/null 2>&1 \
+    || pb_fail state_malformed "state file is not a version-2 pr-babysit state: $state_file" "$(jq -c '{source:"state", version:(.version // null)}' "$state_file")"
+  PB_STATE_REPO=$(jq -r '.repo' "$state_file")
+  PB_STATE_NUMBER=$(jq -r '.number' "$state_file")
+  # These are spliced into REST paths: refuse anything but owner/name and an
+  # integer, whatever a hand-edited state file says.
+  # GitHub owner/name: no leading dot, so `.`/`..` segments cannot form.
+  [[ "$PB_STATE_REPO" =~ ^[A-Za-z0-9][A-Za-z0-9_-]*/[A-Za-z0-9_][A-Za-z0-9._-]*$ ]] \
+    || pb_fail state_malformed "state file repo is not owner/name: $PB_STATE_REPO" '{"source":"state"}'
+  [[ "$PB_STATE_NUMBER" =~ ^[0-9]+$ ]] \
+    || pb_fail state_malformed "state file number is not an integer: $PB_STATE_NUMBER" '{"source":"state"}'
+  PB_STATE_HEAD=$(jq -r '.pr.headSha // ""' "$state_file")
+  export PB_STATE_REPO PB_STATE_NUMBER PB_STATE_HEAD
+}
+
+# pb_state_update STATE_FILE FILTER [JQ_ARGS...] — apply a jq filter to the
+# state and write it back atomically. The filter must yield the whole state.
+pb_state_update() {
+  local state_file="$1" filter="$2"; shift 2
+  pb_atomic_write_json "$state_file" jq -c "$@" "$filter" "$state_file" \
+    || pb_fail state_malformed "could not update $state_file" '{"source":"state"}'
+}

package/plugins/pr-babysit/scripts/parse-verdict.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# parse-verdict.sh — turn the CI review bot's issue comment (stdin) into a
+# deterministic JSON verdict the babysit loop acts on. Keeps the parsing OUT of
+# the LLM prompt so behaviour is testable (scripts/__tests__/parse-verdict.bats
+# against a captured real comment) and stable.
+#
+# stdin : raw comment body (markdown)
+# stdout: { is_review_comment, state, complete, verdict, verdict_label, findings[], must_fix[] }
+#   state: in_progress | complete | unknown
+#     - unknown  → no checkbox checklist found (cannot judge completeness; the
+#                  caller degrades to GitHub check-conclusion behaviour)
+#     - in_progress → ≥1 unchecked `- [ ]` (review still running; do not act)
+#     - complete → ≥1 checkbox AND none unchecked
+#   findings[]: { path, line|null, severity, text, key }  (key = path:line:sha1(text)[:8])
+#   must_fix[]:  free-text lines from `### Top-N must-fix`
+#
+# state can also be "provider_error": the action posted a comment but the model
+# never produced a usable review — "Review incomplete — provider error", every
+# file marked unreviewed. That is NOT a verdict about the code, and the check
+# still reports success, so a caller that reads only `verdict` sees a plain
+# `changes` with no findings and cannot tell "reviewed, nothing actionable"
+# from "never reviewed". complete is false for this state.
+#
+# must_fix is NOT a duplicate of findings. The bot populates the two sections
+# independently, and they disagree in both directions: a review has reported
+# `Findings (0)` while Top-N listed three actionable items, and an `approved`
+# verdict has shipped with Top-N still populated. A caller that reads only
+# findings[] therefore both misses work and over-trusts a pass. These are plain
+# sentences, not `path:line` findings, so they carry no key and cannot be
+# resolved as threads — surface them to a human rather than acting on them
+# mechanically.
+#
+# Identification is by MARKER, robust to both header states the bot uses
+# ("PR Review in Progress" → "Code Review —"): a CI job link, a "Code Review"
+# header, or an "agent-merge" verdict label. No marker → is_review_comment:false.
+set -o pipefail
+
+command -v jq >/dev/null 2>&1 || { echo "parse-verdict.sh: jq required" >&2; exit 2; }
+
+input=$(cat 2>/dev/null || true)
+
+_empty() { jq -nc '{is_review_comment:false, state:"unknown", complete:false, verdict:"none", verdict_label:"", findings:[]}'; }
+
+# Empty / unreadable stdin → not a review comment.
+[ -n "${input//[[:space:]]/}" ] || { _empty; exit 0; }
+
+# --- Identify: marker-based, both states ---
+# Precondition: the babysit pre-filters comments to the CI Toolu Code Review
+# poster (`github-actions[bot]`; legacy `claude[bot]` still accepted) before calling
+# this; the markers below are anchored to the bot's own structures
+# (review headings, the [View job] CI link, a backticked agent-merge label) so a
+# stray "actions/runs/…" or "agent-merge-…" in arbitrary prose won't false-positive.
+is_review=false
+if printf '%s' "$input" | grep -qE '^### Code Review|^### PR Review in Progress|\[View job\]\([^)]*actions/runs/[0-9]+|`agent-merge-[a-z]|^`(merge-approved|request-changes)`$'; then
+  is_review=true
+fi
+if [ "$is_review" != true ]; then _empty; exit 0; fi
+
+# --- Completeness: checkbox state only ---
+unchecked=$(printf '%s\n' "$input" | grep -cE '^[[:space:]]*-[[:space:]]\[[[:space:]]\]' || true)
+checked=$(printf '%s\n'   "$input" | grep -cE '^[[:space:]]*-[[:space:]]\[[xX]\]'        || true)
+boxes=$((unchecked + checked))
+if   [ "$boxes" -eq 0 ];     then state="unknown"
+elif [ "$unchecked" -gt 0 ]; then state="in_progress"
+else                              state="complete"
+fi
+complete=false; [ "$state" = complete ] && complete=true
+
+# --- Verdict --- the machine-readable label is AUTHORITATIVE.
+# Don't infer from prose when a label exists: finding TEXT routinely discusses
+# "Changes requested"/"approved" (e.g. a finding about verdict parsing itself),
+# and a whole-body grep would misclassify an approved PR as "changes". Fall back
+# to prose only when no label is present (changes-first there, as the safe bias).
+#
+# The label has two historical shapes and BOTH must parse:
+#   legacy (<=PR#31): `agent-merge-approved` / `agent-merge-blocked`
+#   current:          `merge-approved` / `request-changes`
+# Resolution order matters. The checklist line `- [x] Set verdict label (`X`)`
+# is preferred because it is emitted before the findings section, so a finding
+# that quotes a label verbatim cannot shadow it. Next the standalone trailing
+# label chip (current shape emits only that). Only then a bare legacy scan.
+verdict_label=$(printf '%s\n' "$input" \
+  | grep -oE 'Set verdict label \(`[^`]+`\)' | head -1 | grep -oE '`[^`]+`' | tr -d '`' || true)
+if [ -z "$verdict_label" ]; then
+  verdict_label=$(printf '%s\n' "$input" \
+    | grep -oE '^`(agent-merge-[a-z-]+|merge-approved|request-changes)`$' | tail -1 | tr -d '`' || true)
+fi
+if [ -z "$verdict_label" ]; then
+  verdict_label=$(printf '%s' "$input" | grep -oE 'agent-merge-[a-z-]+' | head -1 || true)
+fi
+
+# `merge-approved` contains "approved"; `request-changes` contains "changes";
+# `agent-merge-blocked` contains "blocked". Test approved first so the shared
+# substring "merge" in either label can never decide the branch.
+if [[ "$verdict_label" == *approved* ]]; then
+  verdict="approved"
+elif [[ "$verdict_label" == *blocked* || "$verdict_label" == *changes* ]]; then
+  verdict="changes"
+else
+  # No label. Prefer the single `**Verdict:**` summary line over a whole-body
+  # grep: the current bot bolds the KEY (`**Verdict:** ✅ Approved`), not the
+  # word, so the legacy `**Approved**` pattern never matches it.
+  vline=$(printf '%s\n' "$input" | grep -m1 -E '^\*\*Verdict:\*\*' || true)
+  if   printf '%s' "$vline" | grep -qiE 'changes requested'; then verdict="changes"
+  elif printf '%s' "$vline" | grep -qiE 'approved';          then verdict="approved"
+  elif printf '%s' "$input" | grep -qiE '\*\*Changes requested\*\*|changes-requested'; then verdict="changes"
+  elif printf '%s' "$input" | grep -qiE '\*\*Approved\*\*'; then verdict="approved"
+  else verdict="none"
+  fi
+fi
+
+# --- Provider error: the action ran, the model did not. Detected before the
+# findings block because there is nothing to find — the review never happened,
+# and reporting its absence as a normal `changes` verdict is what lets a
+# transient failure look like a considered judgement.
+verdict_line=$(printf '%s\n' "$input" | grep -m1 -E '^\*\*Verdict:\*\*' || true)
+if printf '%s' "$verdict_line" | grep -qiE 'review incomplete|provider error'; then
+  state="provider_error"
+  complete=false
+fi
+
+# --- Findings: only the `### Findings` … next `### ` block, lines of the form
+#     `path[:line]`: severity: text
+_sha1() { (sha1sum 2>/dev/null || shasum 2>/dev/null || echo nohash) | cut -c1-8; }
+# Tolerate a decorated header (`### Findings`, `### Findings (6)`) — exact-match
+# would miss a count suffix and silently report zero findings.
+findings_block=$(printf '%s\n' "$input" | awk '/^### Findings([[:space:]]|$)/{f=1;next} /^### /{f=0} f')
+findings_json="[]"
+while IFS= read -r line; do
+  [[ "$line" =~ ^\`([^\`]+)\`:\ (blocker|high|medium|low|nit):\ (.*)$ ]] || continue
+  raw_path="${BASH_REMATCH[1]}"; sev="${BASH_REMATCH[2]}"; text="${BASH_REMATCH[3]}"
+  if [[ "$raw_path" =~ ^(.+):([0-9]+)$ ]]; then path="${BASH_REMATCH[1]}"; ln="${BASH_REMATCH[2]}"; else path="$raw_path"; ln=""; fi
+  h=$(printf '%s' "$text" | _sha1)
+  key="${path}:${ln}:${h}"
+  obj=$(jq -nc --arg path "$path" --arg line "$ln" --arg severity "$sev" --arg text "$text" --arg key "$key" \
+    '{path:$path, line:(if $line=="" then null else ($line|tonumber) end), severity:$severity, text:$text, key:$key}') || continue
+  findings_json=$(jq -c --argjson o "$obj" '. + [$o]' <<<"$findings_json")
+done <<< "$findings_block"
+
+# --- Top-N must-fix: free-text lines until the next heading or <details>.
+# Same decorated-header tolerance as Findings above; entries may be bare lines
+# or markdown list items.
+must_fix_block=$(printf '%s\n' "$input" | awk 'BEGIN{IGNORECASE=1} /^###[[:space:]]+Top-N[[:space:]]+must-fix([[:space:]]|$)/{f=1;next} /^### |^<details>/{f=0} f')
+must_fix_json="[]"
+while IFS= read -r line; do
+  line="${line#"${line%%[![:space:]]*}"}"
+  line="${line%"${line##*[![:space:]]}"}"
+  [ -n "$line" ] || continue
+  # Strip a leading list marker only — "- " or "1. ". A blanket "first word"
+  # strip ate the first word of every unmarked line ("Fix the silent
+  # swallowing..." became "the silent swallowing...").
+  line="${line#- }"
+  line="${line#\* }"
+  [[ "$line" =~ ^[0-9]+\.[[:space:]]+(.*)$ ]] && line="${BASH_REMATCH[1]}"
+  [ -n "$line" ] || continue
+  if ! next_json=$(jq -c --arg t "$line" '. + [$t]' <<<"$must_fix_json"); then
+    printf 'parse-verdict: could not record a Top-N line; dropping it: %s\n' "$line" >&2
+    continue
+  fi
+  must_fix_json="$next_json"
+done <<< "$must_fix_block"
+
+jq -nc \
+  --argjson is_review "$is_review" \
+  --arg state "$state" \
+  --argjson complete "$complete" \
+  --arg verdict "$verdict" \
+  --arg verdict_label "${verdict_label:-}" \
+  --argjson findings "$findings_json" \
+  --argjson must_fix "$must_fix_json" \
+  '{is_review_comment:$is_review, state:$state, complete:$complete, verdict:$verdict, verdict_label:$verdict_label, findings:$findings, must_fix:$must_fix}'

package/plugins/pr-babysit/scripts/record.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# record.sh — hand the agent's decisions back to the reducer.
+#
+# Usage: record.sh flag-injection --state-file <path> --thread <graphqlId>
+#        record.sh round          --state-file <path> --had-rejection true|false [--fix-pushed]
+#        record.sh status         --state-file <path> --status complete|escalated|cancelled
+#
+#   flag-injection  the reducer drops the thread from actionable and from the
+#                   resolution audit, and lists it under flaggedInjection.
+#   round           end of Step 4, before the push: this round's finding keys
+#                   become lastRoundFindingKeys, lastRoundHadRejection is set,
+#                   and --fix-pushed bumps fixAttempts (cap 5). Recurrence and
+#                   fix budgets therefore advance on real rounds, never polls.
+#   status          the workflow's terminal transition; the reducer only ever
+#                   recommends through `decision`.
+# Every subcommand takes the slot lock, validates the state, writes atomically
+# and prints {ok:true,...}. Exit: 0 · 2 usage · 3 state_malformed · 75 locked.
+set -euo pipefail
+
+PB_SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
+# shellcheck source=lib/common.sh
+. "$PB_SCRIPT_DIR/lib/common.sh"
+# shellcheck source=lib/lock.sh
+. "$PB_SCRIPT_DIR/lib/lock.sh"
+# shellcheck source=lib/state.sh
+. "$PB_SCRIPT_DIR/lib/state.sh"
+
+sub="${1:-}"; [ $# -gt 0 ] && shift
+state_file=""; thread=""; had_rejection=""; fix_pushed=0; status=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --state-file)    state_file="${2:-}"; shift 2 ;;
+    --thread)        thread="${2:-}"; shift 2 ;;
+    --had-rejection) had_rejection="${2:-}"; shift 2 ;;
+    --fix-pushed)    fix_pushed=1; shift ;;
+    --status)        status="${2:-}"; shift 2 ;;
+    *) pb_fail usage "record.sh: unknown argument: $1" ;;
+  esac
+done
+[ -n "$state_file" ] || pb_fail usage "record.sh: --state-file required"
+case "$sub" in
+  flag-injection) [ -n "$thread" ] || pb_fail usage "record.sh flag-injection: --thread <graphqlId> required" ;;
+  round) [[ "$had_rejection" =~ ^(true|false)$ ]] || pb_fail usage "record.sh round: --had-rejection true|false required" ;;
+  status) [[ "$status" =~ ^(complete|escalated|cancelled)$ ]] || pb_fail usage "record.sh status: --status complete|escalated|cancelled required" ;;
+  *) pb_fail usage "record.sh: subcommand must be flag-injection, round or status" ;;
+esac
+
+pb_require jq
+pb_init
+pb_lock_acquire "$state_file" || pb_lock_fail "$state_file"
+pb_state_load "$state_file"
+now=$(pb_now)
+
+case "$sub" in
+  flag-injection)
+    pb_state_update "$state_file" '.actions.flagged[$t] = {reason:"injection", at:$now}' --arg t "$thread" --arg now "$now"
+    jq -nc --arg t "$thread" --arg now "$now" '{ok:true, recorded:"flag-injection", thread:$t, at:$now}' ;;
+  round)
+    pb_state_update "$state_file" \
+      '.pr.lastRoundFindingKeys = (.pr.botFindingKeys // [])
+       | .pr.lastRoundHadRejection = $rej
+       | .pr.fixAttempts = (if $fix then ([(.pr.fixAttempts // 0) + 1, 5] | min) else (.pr.fixAttempts // 0) end)
+       | .lastRound = {at:$now, hadRejection:$rej, fixPushed:$fix, headSha:(.pr.headSha // null)}' \
+      --argjson rej "$had_rejection" --argjson fix "$([ "$fix_pushed" -eq 1 ] && echo true || echo false)" --arg now "$now"
+    jq -c '{ok:true, recorded:"round", lastRoundFindingKeys:.pr.lastRoundFindingKeys, lastRoundHadRejection:.pr.lastRoundHadRejection, fixAttempts:.pr.fixAttempts}' "$state_file" ;;
+  status)
+    pb_state_update "$state_file" '.status = $s | .statusChangedAt = $now' --arg s "$status" --arg now "$now"
+    jq -nc --arg s "$status" --arg now "$now" '{ok:true, recorded:"status", status:$s, at:$now}' ;;
+esac

package/plugins/pr-babysit/scripts/reduce-state.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# reduce-state.sh — the pure decision layer of the pr-babysit helper.
+#
+# Reads one snapshot (collect-pr.sh output) and the previous slot state, and
+# emits the next state plus the compact agent-facing result. No network, no
+# clock (--now is an input), no side effects beyond the two output files, so
+# every decision rule below is testable against captured real snapshots.
+#
+# Usage: reduce-state.sh --snapshot <path> --state <path> --now <iso8601>
+#                        [--state-out <path>] [--result-out <path>]
+#                        [--state-path <path>] [--snapshot-path <path>]
+#   --state         previous state file; absent file = first tick
+#   --state-out     where to write the next state (skipped when omitted)
+#   --result-out    where to write the result (stdout when omitted)
+#   --state-path / --snapshot-path  the paths reported inside the result
+#
+# The rules encoded here are the workflow's (workflows/babysit.md): the Step 1
+# actionable filter and resolution audit, the Step 4 recurrence gate and the
+# Step 6 stop conditions. Reason and error codes are closed sets — see the spec
+# docs/toolu/specs/2026-09-19-pr-babysit-helper-design.md.
+# Exit: 0 result produced · 2 usage · 3 state_malformed | slot_mismatch | invalid_json.
+set -euo pipefail
+
+PB_SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
+# shellcheck source=lib/common.sh
+. "$PB_SCRIPT_DIR/lib/common.sh"
+# shellcheck source=lib/normalize.sh
+. "$PB_SCRIPT_DIR/lib/normalize.sh"
+
+snapshot=""; state=""; now=""; state_out=""; result_out=""; state_path=""; snapshot_path=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --snapshot)      snapshot="${2:-}"; shift 2 ;;
+    --state)         state="${2:-}"; shift 2 ;;
+    --now)           now="${2:-}"; shift 2 ;;
+    --state-out)     state_out="${2:-}"; shift 2 ;;
+    --result-out)    result_out="${2:-}"; shift 2 ;;
+    --state-path)    state_path="${2:-}"; shift 2 ;;
+    --snapshot-path) snapshot_path="${2:-}"; shift 2 ;;
+    *) pb_fail usage "reduce-state.sh: unknown argument: $1" ;;
+  esac
+done
+[ -n "$snapshot" ] || pb_fail usage "reduce-state.sh: --snapshot <path> required"
+[ -n "$state" ] || pb_fail usage "reduce-state.sh: --state <path> required"
+[[ "$now" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$ ]] || pb_fail usage "reduce-state.sh: --now must be an ISO-8601 UTC timestamp (YYYY-MM-DDTHH:MM:SSZ)"
+[ -n "$state_path" ] || state_path="$state"
+[ -n "$snapshot_path" ] || snapshot_path="$snapshot"
+pb_require jq
+
+# --- validate inputs (fail closed, never write) ------------------------------
+[ -f "$snapshot" ] || pb_fail invalid_json "reduce-state.sh: snapshot not found: $snapshot" '{"source":"snapshot"}'
+pb_json_valid "$snapshot" || pb_fail invalid_json "reduce-state.sh: snapshot is not valid JSON: $snapshot" '{"source":"snapshot"}'
+jq -e '.version == 1 and (.repo | type == "string") and (.number | type == "number") and (.head.sha | type == "string") and (.pr | type == "object") and (.threads | type == "array")' "$snapshot" >/dev/null 2>&1 \
+  || pb_fail invalid_json "reduce-state.sh: snapshot is not a version-1 pr-babysit snapshot" '{"source":"snapshot"}'
+
+prev_json="null"
+if [ -e "$state" ]; then
+  pb_json_valid "$state" || pb_fail state_malformed "reduce-state.sh: state file is not valid JSON: $state" '{"source":"state"}'
+  jq -e '.version == 2' "$state" >/dev/null 2>&1 \
+    || pb_fail state_malformed "reduce-state.sh: state file is not version 2: $state" "$(jq -c '{source:"state", version: (.version // null)}' "$state")"
+  if ! jq -e --slurpfile s "$snapshot" '.repo == $s[0].repo and .number == $s[0].number' "$state" >/dev/null 2>&1; then
+    pb_fail slot_mismatch "reduce-state.sh: state belongs to $(jq -r '"\(.repo)#\(.number)"' "$state"), snapshot is $(jq -r '"\(.repo)#\(.number)"' "$snapshot")" \
+      "$(jq -c --slurpfile s "$snapshot" '{source:"state", state:{repo, number}, snapshot:{repo:$s[0].repo, number:$s[0].number}}' "$state")"
+  fi
+  prev_json=$(cat "$state")
+fi
+
+# --- the reducer -------------------------------------------------------------
+pb_jq_reduce() {
+  pb_jq_defs
+  cat <<'EOF'
+# ---- injection heuristics (advisory only): the agent keeps the decision.
+def injection_pattern:
+  . as $b
+  | [ "ignore (all |any |the )?(previous|prior|above|earlier) (instructions|prompts?|rules)",
+      "disregard (all |any |the |your )?(previous|prior|system|above) ",
+      "you are (now )?(an? )?(ai|assistant|llm|language model|claude|codex|copilot)",
+      "(^|\\n)\\s*(system|assistant)\\s*:",
+      "<(system|instructions?)>",
+      "(run|execute) (the following|this|these) (command|shell|script)" ]
+  | map(. as $p | select($b | test($p; "i"))) | first // null;
+# author_class: ci_reviewer (by exact login) | bot (GraphQL Bot / REST type) | human.
+def author_class: if (.author | is_ci_reviewer) then "ci_reviewer" elif .authorType == "Bot" then "bot" else "human" end;
+# ---- inputs
+$snap as $snap | $prev as $prev
+| ($snap.pr) as $pr
+| ($snap.head.sha) as $head
+| ($pr.author) as $author
+| (($snap.repo | ascii_downcase | gsub("/"; "-")) + "-" + ($snap.number | tostring)) as $slot
+| ($snap.repo + "#" + ($snap.number | tostring)) as $key
+| (if $prev == null then {replied:{}, resolved:{}, flagged:{}} else ($prev.actions // {replied:{}, resolved:{}, flagged:{}}) end) as $actions
+| ($actions.flagged | keys) as $flagged
+| ($actions.replied | keys) as $repliedKeys
+# ---- CI
+| ($pr.statusCheckRollup // []) as $rollup
+| ($rollup | ci_status) as $ciStatus
+| ($rollup | map({name: check_name, status: check_state, url: check_url})) as $checks
+# ---- verdict
+| ($snap.bot.verdict // {}) as $v
+| ($snap.bot.comment) as $botComment
+| ($v.state // "absent") as $botState
+| ($v.verdict // "none") as $botVerdict
+| (($v.findings // []) | map(.key)) as $keys
+| (($v.findings // []) | length) as $findingsCount
+| ($botState == "absent" or $botState == "unknown" or ($v.is_review_comment == false)) as $degraded
+| (if $botState == "absent" then "review_absent" elif $degraded then "review_unknown_format" else null end) as $degradedReason
+| ($prev != null and $botComment != null and ($prev.pr.botCommentId // null) == $botComment.id and ($prev.pr.botCommentUpdatedAt // null) == $botComment.updatedAt) as $sameRun
+# ---- thread classification
+| ($snap.threads | map(
+    . as $t
+    | ($t.comments | last) as $lastComment
+    | ($t.comments | map(select(.author != $author)) | last) as $lastNonAuthor
+    | ($flagged | index($t.id) != null) as $isFlagged
+    | (if $lastNonAuthor == null then "none" else ($lastNonAuthor | author_class) end) as $class
+    | ($t.isResolved == false) as $open
+    | ($open and ($isFlagged | not) and $lastComment != null and $lastComment.author != $author and ($class == "human" or $class == "ci_reviewer")) as $answerable
+    | (if $t.isOutdated then ($answerable and $class == "human") else $answerable end) as $actionable
+    | ($open and ($t.isOutdated | not) and ($isFlagged | not)) as $audited
+    | { id: $t.id, path: $t.path, line: $t.line, isOutdated: $t.isOutdated, isResolved: $t.isResolved,
+        rootCommentId: ($t.comments | first | .databaseId // null),
+        inReplyTo: ($lastNonAuthor.databaseId // null),
+        authorClass: $class,
+        lastCommentAuthor: ($lastComment.author // null),
+        lastCommentAt: ($lastComment.createdAt // null),
+        injectionSuspect: ((($lastNonAuthor.body // "") | injection_pattern) != null),
+        injectionPattern: (($lastNonAuthor.body // "") | injection_pattern),
+        comments: $t.comments,
+        flags: {actionable: $actionable, audited: $audited, flagged: $isFlagged,
+                skippedOutdated: ($open and $t.isOutdated and $class == "ci_reviewer"),
+                replied: ($repliedKeys | index("thread:" + $t.id + "@" + (($lastNonAuthor.databaseId // 0) | tostring)) != null)} }
+  )) as $threads
+| ($threads | map(select(.flags.actionable)) | map(del(.flags, .isResolved))) as $actionable
+| ($threads | map(select(.flags.audited))) as $audited
+| ($audited | map(select(.flags.actionable | not)) | map({id, path, line, repliedAt: .lastCommentAt, lastCommentAuthor})) as $staleUnresolved
+| ($threads | map(select(.flags.skippedOutdated)) | map(.id)) as $skippedOutdated
+| ($threads | map(select(.flags.flagged)) | map(.id)) as $flaggedInjection
+| ($audited | length) as $unresolved
+# ---- conversation and review-level comments
+| (($snap.comments // []) | map(select(.author != $author and .authorType != "Bot"))
+    | map(. as $c | select(($snap.comments | map(select(.author == $author and .createdAt > $c.createdAt)) | length) == 0))
+    | map(. as $c | select(($repliedKeys | index("conversation:" + ($c.id | tostring))) == null))
+    | map({id, author, body, createdAt, url})) as $convActionable
+| (($snap.reviews // []) | map(select(.author != $author and .authorType != "Bot" and .state != "APPROVED" and ((.body // "") | length) > 0))
+    | map(. as $r | select(($repliedKeys | index("review:" + ($r.id | tostring))) == null))
+    | map({id, author, state, body, submittedAt, url})) as $reviewActionable
+# ---- recurrence (Step 4 gate) — only a NEW verdict run can recur
+| (if $prev == null then [] else ($prev.pr.lastRoundFindingKeys // []) end) as $lastRoundKeys
+| (if $prev == null then false else ($prev.pr.lastRoundHadRejection // false) end) as $lastRoundHadRejection
+| (if $prev == null then 0 else ($prev.pr.recurrenceStreak // 0) end) as $prevStreak
+| (if $prev == null then 0 else ($prev.pr.fixAttempts // 0) end) as $fixAttempts
+| (if $sameRun or $prev == null then [] else ($keys | map(select(. as $k | $lastRoundKeys | index($k) != null))) end) as $recurringKeys
+| (if $sameRun then $prevStreak elif ($recurringKeys | length) > 0 then ($prevStreak + 1) else 0 end) as $streak
+# ---- change detection + backoff
+| ({ciStatus: $ciStatus, reviewDecision: $pr.reviewDecision, mergeable: $pr.mergeable, unresolvedThreads: $unresolved,
+    headSha: $head, botVerdict: $botVerdict, botState: $botState, botFindingKeys: $keys}) as $cmp
+| ($prev == null or ($prev.pr | {ciStatus, reviewDecision, mergeable, unresolvedThreads, headSha, botVerdict, botState, botFindingKeys}) != $cmp) as $changed
+| (if $changed then 0 else (($prev.idleStreak // 0) + 1) end) as $idleStreak
+| (if $idleStreak >= 9 then 15 elif $idleStreak >= 6 then 12 elif $idleStreak >= 3 then 6 elif $ciStatus == "fail" then 1 else 3 end) as $intervalMinutes
+| (if $idleStreak >= 6 then 60 elif $idleStreak >= 3 then 30 else 15 end) as $waitSeconds
+# ---- decision (Step 6)
+| ($prev != null and $botState == "provider_error" and ($prev.pr.botState // "") == "provider_error" and ($prev.pr.headSha // "") == $head) as $providerErrorRepeated
+| ([ (if $pr.state == "MERGED" then {code:"pr_merged", detail:"PR is merged"} else empty end),
+     (if $pr.state == "CLOSED" then {code:"pr_closed", detail:"PR is closed"} else empty end),
+     (if $pr.mergeable == "CONFLICTING" then {code:"merge_conflict", detail:"mergeable is CONFLICTING"} else empty end),
+     (if $fixAttempts >= 5 then {code:"fix_attempts_exhausted", detail:"\($fixAttempts) fix attempts recorded"} else empty end),
+     (if ($recurringKeys | length) > 0 and $lastRoundHadRejection then {code:"recurrence_after_rejection", detail:"\($recurringKeys | length) finding key(s) recurred after a Won't-fix round"} else empty end),
+     (if ($recurringKeys | length) > 0 and $streak >= 2 then {code:"recurrence_streak", detail:"finding keys recurred on \($streak) consecutive rounds"} else empty end),
+     (if $providerErrorRepeated then {code:"provider_error_repeated", detail:"review provider error twice on head \($head[0:8])"} else empty end)
+   ]) as $escalations
+| ([ (if $ciStatus == "pass" then {code:"ci_pass", detail:"\($checks | length) check(s) passed"}
+      elif $ciStatus == "fail" then {code:"ci_failed", detail:($checks | map(select(.status == "fail")) | map(.name) | join(", "))}
+      else {code:"ci_pending", detail:(if ($checks | length) == 0 then "no checks reported yet" else ($checks | map(select(.status == "pending")) | map(.name) | join(", ")) end)} end),
+     (if $unresolved == 0 then {code:"threads_clear", detail:"no unresolved review threads"} else empty end),
+     (if ($actionable | length) > 0 then {code:"threads_unresolved", detail:"\($actionable | length) actionable thread(s)"} else empty end),
+     (if ($staleUnresolved | length) > 0 then {code:"threads_stale_unresolved", detail:"\($staleUnresolved | length) replied-but-unresolved thread(s)"} else empty end),
+     (if $botState == "in_progress" then {code:"review_in_progress", detail:"review bot still running"}
+      elif $botState == "provider_error" and ($providerErrorRepeated | not) then {code:"provider_error", detail:"review bot reported a provider error; rerun the review job once"}
+      elif $botState == "complete" and $botVerdict == "approved" and $findingsCount == 0 then {code:"review_approved", detail:"bot verdict approved with zero findings"}
+      elif $botState == "complete" then {code:"review_changes", detail:"bot verdict \($botVerdict) with \($findingsCount) finding(s)"}
+      elif $degraded then {code:$degradedReason, detail:"bot verdict cannot be read"} else empty end),
+     (if $degraded then {code:"manual_verify", detail:"verify review findings manually: \($botComment.url // "no bot comment")"} else empty end),
+     (if $pr.mergeable == "UNKNOWN" and $pr.state == "OPEN" then {code:"mergeable_unknown", detail:"GitHub has not computed mergeability yet"} else empty end),
+     (if $changed then empty else {code:"unchanged", detail:"nothing changed since the last tick"} end)
+   ]) as $signals
+| (($escalations | length) > 0) as $escalate
+| ($pr.state == "OPEN" and $ciStatus == "pass" and $unresolved == 0 and $pr.mergeable != "UNKNOWN"
+   and ( ($botState == "complete" and $botVerdict == "approved" and $findingsCount == 0) or $degraded )) as $successReady
+| (if $escalate then "escalate" elif $successReady then "success" else "keep_going" end) as $decision
+| ($escalations + $signals) as $reasons
+# ---- outputs
+| {
+  state: {
+    version: 2, slot: $slot, repo: $snap.repo, number: $snap.number,
+    cronName: ("pr-babysit:" + $slot),
+    lastUpdate: $now,
+    totalTicks: ((if $prev == null then 0 else ($prev.totalTicks // 0) end) + 1),
+    idleStreak: $idleStreak, currentInterval: $intervalMinutes, waitSeconds: $waitSeconds,
+    status: (if $prev == null then "active" else ($prev.status // "active") end),
+    worktree: (if $prev == null then null else ($prev.worktree // null) end),
+    pr: {
+      key: $key, ciStatus: $ciStatus, reviewDecision: $pr.reviewDecision, mergeable: $pr.mergeable,
+      unresolvedThreads: $unresolved, headSha: $head, fixAttempts: $fixAttempts,
+      botVerdict: $botVerdict, botState: $botState,
+      botCommentId: ($botComment.id // null), botCommentUpdatedAt: ($botComment.updatedAt // null),
+      botFindingKeys: $keys, lastRoundFindingKeys: $lastRoundKeys, lastRoundHadRejection: $lastRoundHadRejection,
+      recurrenceStreak: $streak, unresolvedAfterClearance: $unresolved, lastError: null
+    },
+    actions: $actions,
+    lastGoodSnapshot: $snapshotPath
+  },
+  result: {
+    version: 1, slot: $slot, changed: $changed, decision: $decision, reasons: $reasons,
+    pr: {number: $pr.number, url: $pr.url, head: $head, branch: $pr.headRefName, base: $pr.baseRefName, author: $author,
+         state: $pr.state, mergeable: $pr.mergeable, reviewDecision: $pr.reviewDecision},
+    ci: {status: $ciStatus, checks: $checks},
+    verdict: {state: $botState, verdict: $botVerdict, findingsCount: $findingsCount, findingKeys: $keys,
+              mustFix: ($v.must_fix // []), commentUrl: ($botComment.url // null), commentId: ($botComment.id // null),
+              degraded: $degraded, degradedReason: $degradedReason, sameRunAsLastTick: $sameRun},
+    threads: {total: ($snap.threads | length), unresolved: $unresolved,
+              actionable: $actionable, staleUnresolved: $staleUnresolved,
+              skippedOutdated: $skippedOutdated, flaggedInjection: $flaggedInjection},
+    conversation: {actionable: $convActionable},
+    reviews: {actionable: $reviewActionable},
+    recurrence: {streak: $streak, lastRoundHadRejection: $lastRoundHadRejection, recurringKeys: $recurringKeys, fixAttempts: $fixAttempts},
+    backoff: {idleStreak: $idleStreak, intervalMinutes: $intervalMinutes, waitSeconds: $waitSeconds},
+    errors: [], snapshotPath: $snapshotPath, statePath: $statePath
+  }
+}
+EOF
+}
+
+combined=$(jq -n \
+  --slurpfile snapfile "$snapshot" --argjson prev "$prev_json" \
+  --arg now "$now" --arg statePath "$state_path" --arg snapshotPath "$snapshot_path" \
+  '$snapfile[0] as $snap | $prev as $prev | $now as $now | $statePath as $statePath | $snapshotPath as $snapshotPath | '"$(pb_jq_reduce)") \
+  || pb_fail invalid_json "reduce-state.sh: reducer failed on $snapshot" '{"source":"reduce"}'
+
+if [ -n "$state_out" ]; then
+  pb_atomic_write_json "$state_out" jq -c '.state' <<<"$combined" || pb_fail invalid_json "reduce-state.sh: could not write $state_out" '{"source":"state_out"}'
+fi
+if [ -n "$result_out" ]; then
+  pb_atomic_write_json "$result_out" jq -c '.result' <<<"$combined" || pb_fail invalid_json "reduce-state.sh: could not write $result_out" '{"source":"result_out"}'
+else
+  jq -c '.result' <<<"$combined"
+fi