@toolu/opencode 6.8.0

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

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# collect-pr.sh — the read side of the pr-babysit helper.
+#
+# Fetches everything one babysit tick needs from GitHub and writes ONE
+# versioned snapshot. No decisions are made here (see reduce-state.sh); the
+# only judgment is "which comment is the CI reviewer's verdict", delegated to
+# parse-verdict.sh.
+#
+# Usage: collect-pr.sh --repo <owner/repo> --pr <n> --out <path>
+#                      [--page-size N] [--timeout SECONDS]
+#
+# Behavior (spec: docs/toolu/specs/2026-09-19-pr-babysit-helper-design.md):
+#  - four independent reads run concurrently as background jobs (pr view,
+#    review threads, issue comments, reviews), each through lib/gh.sh's
+#    timeout + bounded retry; any failure aborts the whole collection with a
+#    structured error and NO snapshot;
+#  - reviewThreads paginate via `gh api graphql --paginate --slurp`; a
+#    thread whose comments overflow one page is completed with a cursor loop
+#    on node(id:); REST comments/reviews paginate via --paginate --slurp;
+#  - the PR head is read before and after the fan-out; if it moved the whole
+#    collection runs again once, then fails with head_moved;
+#  - the bot comment is the LAST CI-reviewer issue comment that
+#    parse-verdict.sh recognises as a review, else the last CI-reviewer
+#    comment (verdict state unknown), else null (state absent).
+# Exit: 0 snapshot written · 2 usage · 3 structured error (stdout 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/gh.sh
+. "$PB_SCRIPT_DIR/lib/gh.sh"
+# shellcheck source=lib/normalize.sh
+. "$PB_SCRIPT_DIR/lib/normalize.sh"
+
+repo=""; number=""; out=""; page_size=100
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo)      repo="${2:-}"; shift 2 ;;
+    --pr)        number="${2:-}"; shift 2 ;;
+    --out)       out="${2:-}"; shift 2 ;;
+    --page-size) page_size="${2:-}"; shift 2 ;;
+    --timeout)   PB_GH_TIMEOUT="${2:-}"; shift 2 ;;
+    *) pb_fail usage "collect-pr.sh: unknown argument: $1" ;;
+  esac
+done
+[[ "$repo" =~ ^[^/[:space:]]+/[^/[:space:]]+$ ]] || pb_fail usage "collect-pr.sh: --repo <owner/repo> required"
+[[ "$number" =~ ^[0-9]+$ ]] || pb_fail usage "collect-pr.sh: --pr <n> required"
+[ -n "$out" ] || pb_fail usage "collect-pr.sh: --out <path> required"
+[[ "$page_size" =~ ^[0-9]+$ ]] && [ "$page_size" -ge 1 ] || pb_fail usage "collect-pr.sh: --page-size must be a positive integer"
+[[ "$PB_GH_TIMEOUT" =~ ^[0-9]+$ ]] && [ "$PB_GH_TIMEOUT" -ge 1 ] || pb_fail usage "collect-pr.sh: --timeout must be a positive integer"
+
+pb_require jq gh
+pb_init
+pb_mktmpdir
+owner="${repo%%/*}"; name="${repo#*/}"
+PARSER="$(pb_plugin_root)/scripts/parse-verdict.sh"
+# _collect_once returns this when the PR head moved between its two reads.
+PB_HEAD_MOVED_RC=10
+[ -f "$PARSER" ] || pb_fail usage "collect-pr.sh: parse-verdict.sh not found at $PARSER"
+
+# _read_head -> current headRefOid on stdout, or a structured error document
+# on stdout with a non-zero status. It runs inside `$(...)`, so it must NOT
+# exit: an `exit` there only leaves the subshell and the caller would carry
+# on with the error text as a "head". The caller re-emits via _die_with_doc.
+_read_head() {
+  pb_gh "$PB_TMPDIR/head.json" pr view "$number" --repo "$repo" --json headRefOid || {
+    pb_error api_error "gh head failed after ${PB_GH_ATTEMPTED:-0} attempt(s): ${PB_GH_LAST_ERR:-rc ${PB_GH_LAST_RC:-?}}" \
+      "$(jq -nc --argjson attempts "${PB_GH_ATTEMPTED:-0}" --arg class "${PB_GH_CLASS:-}" --arg lastMessage "${PB_GH_LAST_ERR:-}" \
+          '{source:"head", attempts:$attempts, class:$class, lastMessage:$lastMessage}')"
+    return 1
+  }
+  jq -er '.headRefOid' "$PB_TMPDIR/head.json" 2>/dev/null \
+    || { pb_error invalid_json "collect-pr.sh: head read returned no headRefOid" '{"source":"head"}'; return 1; }
+}
+
+# _die_with_doc DOC — re-emit a captured error document on the real stdout
+# and exit with the code it maps to (used after a failed head read).
+_die_with_doc() {
+  printf '%s\n' "$1"
+  exit "$(pb_exit_code "$(jq -r '.errors[0].code // "api_error"' <<<"$1" 2>/dev/null || echo api_error)")"
+}
+
+# _job NAME GH_ARGS... — one background read. Writes NAME.json and NAME.meta
+# (the pb_gh outcome) so the parent can report exactly which read failed.
+_job() {
+  local jname="$1"; shift
+  local rc=0
+  pb_gh "$PB_TMPDIR/$jname.json" "$@" || rc=$?
+  if [ "$rc" -eq 0 ] && ! pb_gh_json_ok "$PB_TMPDIR/$jname.json"; then
+    rc=1; PB_GH_CLASS=invalid_json
+    PB_GH_LAST_ERR="response is not valid JSON or carries GraphQL errors[]"
+  fi
+  jq -nc --argjson rc "$rc" --argjson attempts "${PB_GH_ATTEMPTED:-0}" \
+    --arg class "${PB_GH_CLASS:-}" --arg lastMessage "${PB_GH_LAST_ERR:-}" \
+    '{rc:$rc, attempts:$attempts, class:$class, lastMessage:$lastMessage}' >"$PB_TMPDIR/$jname.meta"
+}
+
+# _fan_out — run the four reads concurrently, then fail on the first bad meta.
+_fan_out() {
+  local j pids=""
+  _job pr pr view "$number" --repo "$repo" --json "$(pb_pr_view_fields)" & pids="$pids $!"
+  # Strings go through -f (raw); -F would coerce a numeric-looking owner or
+  # repo name into a JSON number and break the GraphQL variable types.
+  _job threads api graphql --paginate --slurp \
+    -f owner="$owner" -f repo="$name" -F number="$number" -F pageSize="$page_size" \
+    -f query="$(pb_gql_threads)" & pids="$pids $!"
+  _job comments api --paginate --slurp "repos/$repo/issues/$number/comments?per_page=$page_size" & pids="$pids $!"
+  _job reviews api --paginate --slurp "repos/$repo/pulls/$number/reviews?per_page=$page_size" & pids="$pids $!"
+  for j in $pids; do wait "$j" || true; done
+  for j in pr threads comments reviews; do
+    [ -f "$PB_TMPDIR/$j.meta" ] || pb_fail api_error "collect-pr.sh: read '$j' produced no outcome" "{\"source\":\"$j\"}"
+    if [ "$(jq -r .rc "$PB_TMPDIR/$j.meta")" != 0 ]; then
+      local code=api_error
+      [ "$(jq -r .class "$PB_TMPDIR/$j.meta")" = invalid_json ] && code=invalid_json
+      pb_fail "$code" "collect-pr.sh: read '$j' failed: $(jq -r .lastMessage "$PB_TMPDIR/$j.meta")" \
+        "$(jq -c --arg source "$j" '{source:$source, attempts, class, lastMessage}' "$PB_TMPDIR/$j.meta")"
+    fi
+  done
+}
+
+# _complete_thread_comments — for every thread whose comment page overflowed,
+# follow the cursor on node(id:) and splice the remaining comments in.
+_complete_thread_comments() {
+  local ids tid extra=0
+  ids=$(jq -r '.[] | select(.commentsHasNextPage == true) | .id' "$PB_TMPDIR/threads.norm.json")
+  [ -n "$ids" ] || { echo 0 >"$PB_TMPDIR/threadComments.pages"; return 0; }
+  for tid in $ids; do
+    local cursor
+    cursor=$(jq -r --arg id "$tid" '.[] | select(.id == $id) | .commentsEndCursor' "$PB_TMPDIR/threads.norm.json")
+    # The first page is already in hand: resume from its endCursor.
+    pb_gh "$PB_TMPDIR/tc.json" api graphql --paginate --slurp \
+      -f id="$tid" -F pageSize="$page_size" -f endCursor="$cursor" \
+      -f query="$(pb_gql_thread_comments)" || pb_gh_fail threadComments
+    pb_gh_json_ok "$PB_TMPDIR/tc.json" || pb_fail invalid_json "collect-pr.sh: thread comment page for $tid is not valid JSON" '{"source":"threadComments"}'
+    extra=$((extra + $(jq 'length' "$PB_TMPDIR/tc.json")))
+    jq "$(pb_jq_thread_comments_from_pages)" "$PB_TMPDIR/tc.json" >"$PB_TMPDIR/tc.norm.json"
+    jq --arg id "$tid" --slurpfile more "$PB_TMPDIR/tc.norm.json" \
+      'map(if .id == $id then .comments += $more[0] | .commentsHasNextPage = false | .commentsEndCursor = null else . end)' \
+      "$PB_TMPDIR/threads.norm.json" >"$PB_TMPDIR/threads.norm.next.json"
+    mv "$PB_TMPDIR/threads.norm.next.json" "$PB_TMPDIR/threads.norm.json"
+  done
+  echo "$extra" >"$PB_TMPDIR/threadComments.pages"
+}
+
+# _select_bot_comment — write bot.json: {comment, verdict}.
+_select_bot_comment() {
+  local ids cid body chosen=""
+  ids=$(jq -r "$(pb_jq_defs) [.[] | select(.author | is_ci_reviewer)] | reverse | .[].id" "$PB_TMPDIR/comments.norm.json")
+  for cid in $ids; do
+    body=$(jq -r --argjson id "$cid" '.[] | select(.id == $id) | .body' "$PB_TMPDIR/comments.norm.json")
+    printf '%s' "$body" | bash "$PARSER" >"$PB_TMPDIR/verdict.json"
+    if jq -e '.is_review_comment == true' "$PB_TMPDIR/verdict.json" >/dev/null; then chosen="$cid"; break; fi
+  done
+  if [ -z "$chosen" ]; then
+    # No recognised review: fall back to the last CI-reviewer comment (state
+    # unknown, degraded) or none at all (state absent).
+    chosen=$(printf '%s\n' "$ids" | head -n 1)
+    if [ -n "$chosen" ]; then
+      body=$(jq -r --argjson id "$chosen" '.[] | select(.id == $id) | .body' "$PB_TMPDIR/comments.norm.json")
+      printf '%s' "$body" | bash "$PARSER" >"$PB_TMPDIR/verdict.json"
+    else
+      printf '' | bash "$PARSER" | jq '.state = "absent"' >"$PB_TMPDIR/verdict.json"
+    fi
+  fi
+  if [ -n "$chosen" ]; then
+    jq -c --argjson id "$chosen" --slurpfile v "$PB_TMPDIR/verdict.json" \
+      '{comment: (.[] | select(.id == $id) | {id, url, createdAt, updatedAt, author}), verdict: $v[0]}' \
+      "$PB_TMPDIR/comments.norm.json" >"$PB_TMPDIR/bot.json"
+  else
+    jq -nc --slurpfile v "$PB_TMPDIR/verdict.json" '{comment: null, verdict: $v[0]}' >"$PB_TMPDIR/bot.json"
+  fi
+}
+
+_collect_once() {
+  local head_before head_after
+  head_before=$(_read_head) || _die_with_doc "$head_before"
+  _fan_out
+  jq "$(pb_jq_threads_from_pages)" "$PB_TMPDIR/threads.json" >"$PB_TMPDIR/threads.norm.json"
+  _complete_thread_comments
+  jq "$(pb_jq_rest_items) | map($(pb_jq_issue_comment))" "$PB_TMPDIR/comments.json" >"$PB_TMPDIR/comments.norm.json"
+  jq "$(pb_jq_rest_items) | map($(pb_jq_review))" "$PB_TMPDIR/reviews.json" >"$PB_TMPDIR/reviews.norm.json"
+  _select_bot_comment
+  head_after=$(_read_head) || _die_with_doc "$head_after"
+  if [ "$head_before" != "$head_after" ]; then
+    : >"$PB_TMPDIR/head.moved"
+    return "$PB_HEAD_MOVED_RC"
+  fi
+  printf '%s' "$head_after" >"$PB_TMPDIR/head.sha"
+}
+
+# A moved head (rc 10) earns exactly one more collection; anything else has
+# already exited through pb_fail inside _collect_once.
+moved=0
+if ! pb_retry_on_rc "$PB_HEAD_MOVED_RC" 2 _collect_once; then
+  pb_fail head_moved "collect-pr.sh: PR head moved twice during collection" '{"source":"head"}'
+fi
+[ ! -f "$PB_TMPDIR/head.moved" ] || moved=1
+
+_build_snapshot() {
+  jq -n \
+    --arg collectedAt "$(pb_now)" --arg repo "$repo" --argjson number "$number" \
+    --arg head "$(cat "$PB_TMPDIR/head.sha")" --argjson recollected "$moved" \
+    --argjson pageSize "$page_size" \
+    --slurpfile pr "$PB_TMPDIR/pr.json" \
+    --slurpfile threads "$PB_TMPDIR/threads.norm.json" \
+    --slurpfile comments "$PB_TMPDIR/comments.norm.json" \
+    --slurpfile reviews "$PB_TMPDIR/reviews.norm.json" \
+    --slurpfile bot "$PB_TMPDIR/bot.json" \
+    --argjson pThreads "$(jq 'length' "$PB_TMPDIR/threads.json")" \
+    --argjson pThreadComments "$(cat "$PB_TMPDIR/threadComments.pages")" \
+    --argjson pComments "$(jq 'length' "$PB_TMPDIR/comments.json")" \
+    --argjson pReviews "$(jq 'length' "$PB_TMPDIR/reviews.json")" \
+    '{version: 1, collectedAt: $collectedAt, repo: $repo, number: $number,
+      head: {sha: $head, verifiedAfterFanout: true, recollected: ($recollected == 1)},
+      pageSize: $pageSize,
+      pr: ($pr[0] | {number, title, url, author: (.author.login // null), state, baseRefName, headRefName,
+                     headRefOid, mergeable, reviewDecision, statusCheckRollup: (.statusCheckRollup // [])}),
+      threads: ($threads[0] | map(del(.commentsHasNextPage, .commentsEndCursor))),
+      comments: $comments[0], reviews: $reviews[0], bot: $bot[0],
+      pages: {threads: $pThreads, threadComments: $pThreadComments, comments: $pComments, reviews: $pReviews}}'
+}
+pb_atomic_write_json "$out" _build_snapshot || pb_fail invalid_json "collect-pr.sh: could not assemble the snapshot" '{"source":"snapshot"}'
+printf '%s\n' "$out"

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# common.sh — shared plumbing for the pr-babysit helper scripts.
+#
+# Sourced, never run. Provides: plugin-root resolution from this file's own
+# location (no environment variable names the root), dependency checks, a
+# structured-error emitter with the closed exit-code map, an atomic JSON
+# writer, and the single EXIT handler every entrypoint installs via pb_init.
+#
+# Portability contract (see docs/toolu/specs/2026-09-19-pr-babysit-helper-design.md):
+# bash 3.2 — no mapfile/readarray, no declare -A, no wait -n, no ${var,,}.
+
+# Closed error-code → exit-code map. Adding a code is a schema change.
+#   usage 2 · gh_unavailable/jq_required/api_error/invalid_json/head_moved/
+#   state_malformed/slot_mismatch 3 · duplicate_reply 4 · resolve_unconfirmed 5
+#   locked 75 (EX_TEMPFAIL)
+pb_exit_code() {
+  case "$1" in
+    usage) echo 2 ;;
+    duplicate_reply) echo 4 ;;
+    resolve_unconfirmed) echo 5 ;;
+    locked) echo 75 ;;
+    gh_unavailable|jq_required|api_error|invalid_json|head_moved|state_malformed|slot_mismatch) echo 3 ;;
+    *) echo 3 ;;
+  esac
+}
+
+# pb_plugin_root -> absolute path of plugins/pr-babysit (this file lives in
+# scripts/lib/). Resolved from BASH_SOURCE so an installed copy under any
+# host cache path works without configuration.
+pb_plugin_root() {
+  local here
+  here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P) || return 1
+  (cd "$here/../.." && pwd -P)
+}
+
+# pb_require CMD... -> exit through pb_fail when a dependency is missing.
+pb_require() {
+  local cmd
+  for cmd in "$@"; do
+    command -v "$cmd" >/dev/null 2>&1 && continue
+    case "$cmd" in
+      jq) pb_fail jq_required "jq is required" ;;
+      gh) pb_fail gh_unavailable "gh is required" ;;
+      *)  pb_fail gh_unavailable "$cmd is required" ;;
+    esac
+  done
+}
+
+# pb_error CODE MESSAGE [EXTRA_JSON] -> one structured error document on stdout.
+# EXTRA_JSON (an object) is merged into the error entry.
+pb_error() {
+  local code="$1" message="$2" extra="${3:-}"
+  [ -n "$extra" ] || extra='{}'
+  jq -nc --arg code "$code" --arg message "$message" --argjson extra "$extra" \
+    '{version:1, errors:[({code:$code, message:$message} + $extra)]}'
+}
+
+# pb_fail CODE MESSAGE [EXTRA_JSON] -> emit the error and exit with its code.
+pb_fail() {
+  pb_error "$@"
+  exit "$(pb_exit_code "$1")"
+}
+
+# pb_now -> ISO-8601 UTC timestamp.
+pb_now() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+
+# pb_json_valid FILE -> 0 when FILE parses as JSON.
+pb_json_valid() { jq -e . "$1" >/dev/null 2>&1; }
+
+# pb_atomic_write_json TARGET CMD [ARGS...]
+# Run CMD with stdout captured into a unique temp file beside TARGET, then
+# rename it over TARGET only when CMD exited 0 AND the output parses as JSON.
+# Any failure removes the temp file and leaves TARGET byte-identical, so a
+# reader never sees a partial document and a crashed writer leaves no residue.
+# The in-flight temp file is published so pb_on_exit can remove it when a
+# signal lands mid-write: PB_ATOMIC_PREFIX is set BEFORE mktemp runs (a trap
+# can fire between mktemp returning and the assignment below, so the exact
+# name may never be recorded), and it carries $$ so the sweep only ever
+# touches this process's own temps.
+PB_ATOMIC_TMP=""
+PB_ATOMIC_PREFIX=""
+pb_atomic_write_json() {
+  local target="$1"; shift
+  local dir tmp
+  dir=$(dirname "$target")
+  mkdir -p "$dir" || return 1
+  PB_ATOMIC_PREFIX="$dir/.$(basename "$target").tmp.$$."
+  if ! tmp=$(mktemp "${PB_ATOMIC_PREFIX}XXXXXX"); then
+    PB_ATOMIC_PREFIX=""; return 1
+  fi
+  PB_ATOMIC_TMP="$tmp"
+  if ! "$@" >"$tmp"; then
+    rm -f "$tmp"; PB_ATOMIC_TMP=""; PB_ATOMIC_PREFIX=""; return 1
+  fi
+  if ! pb_json_valid "$tmp"; then
+    rm -f "$tmp"; PB_ATOMIC_TMP=""; PB_ATOMIC_PREFIX=""; return 1
+  fi
+  if ! mv -f "$tmp" "$target"; then
+    rm -f "$tmp"; PB_ATOMIC_TMP=""; PB_ATOMIC_PREFIX=""; return 1
+  fi
+  PB_ATOMIC_TMP=""; PB_ATOMIC_PREFIX=""
+}
+
+# pb_retry_on_rc RETRY_RC ATTEMPTS CMD [ARGS...]
+# Run CMD; while it returns exactly RETRY_RC and attempts remain, run it
+# again. Returns CMD's last exit code. Used for "collect again once when the
+# PR head moved under us": any other failure propagates on the first try.
+pb_retry_on_rc() {
+  local retry_rc="$1" attempts="$2"; shift 2
+  local n=0 rc=0
+  while :; do
+    n=$((n + 1))
+    rc=0
+    "$@" || rc=$?
+    [ "$rc" -eq "$retry_rc" ] || return "$rc"
+    [ "$n" -lt "$attempts" ] || return "$rc"
+    echo "pr-babysit: attempt $n of $attempts returned $rc; retrying $1" >&2
+  done
+}
+
+# pb_mktmpdir -> create the per-run scratch dir (removed by pb_on_exit).
+pb_mktmpdir() {
+  PB_TMPDIR=$(mktemp -d "${TMPDIR:-/tmp}/pr-babysit.XXXXXX") || return 1
+  export PB_TMPDIR
+}
+
+# pb_on_exit — the one EXIT handler: release the slot lock (if held) and
+# remove the scratch dir. Installed by pb_init; scripts never add a second
+# EXIT trap. Runs on signals too (TERM/INT re-raise through EXIT).
+pb_on_exit() {
+  local rc=$?
+  # A second signal must not re-enter `exit` and abort the cleanup midway.
+  trap '' TERM INT
+  if declare -F pb_lock_release >/dev/null 2>&1; then pb_lock_release; fi
+  [ -n "${PB_ATOMIC_TMP:-}" ] && rm -f "$PB_ATOMIC_TMP"
+  [ -n "${PB_ATOMIC_PREFIX:-}" ] && rm -f "${PB_ATOMIC_PREFIX}"*
+  [ -n "${PB_TMPDIR:-}" ] && [ -d "${PB_TMPDIR:-}" ] && rm -rf "$PB_TMPDIR"
+  return "$rc"
+}
+
+# pb_init — install the EXIT handler and forward TERM/INT into it.
+pb_init() {
+  trap pb_on_exit EXIT
+  trap 'exit 143' TERM
+  trap 'exit 130' INT
+}

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

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# gh.sh — bounded `gh` transport for the pr-babysit helper.
+#
+# Sourced after common.sh. Every GitHub call goes through pb_gh so timeouts,
+# retries, and error classification live in one place:
+#
+#   pb_run_with_timeout SECONDS OUT ERR CMD...  run CMD, kill it after SECONDS
+#   pb_gh_classify RC ERR_FILE OUT_FILE         -> transient | permanent | ok
+#   pb_gh OUT_FILE ARGS...                      gh ARGS with retry; stdout → OUT_FILE
+#   pb_gh_json_ok FILE                          -> 0 when FILE is JSON without errors[]
+#
+# GNU `timeout` is absent on macOS and `gh` has no timeout flag, so the
+# watchdog is a background job plus a sleeping killer subshell — bash 3.2 has
+# no `wait -n`, so the job's exit code is read from a status file it writes.
+#
+# Retry policy (spec §Architecture): 3 attempts with waits of 2 s and 4 s
+# between them (the 8 s step of PB_GH_BACKOFF only applies when
+# PB_GH_ATTEMPTS is raised), for timeouts, 5xx, connection errors, HTTP 429,
+# and 403 whose body mentions the rate limit. Any other 4xx is permanent and
+# never retried. Observed real
+# shapes this classifies (2026-09-19, gh 2.101.0):
+#   refused host  → rc 1, stderr `dial tcp 127.0.0.1:1: connect: connection refused`
+#   404           → rc 1, stdout `{"message":"Not Found",…,"status":"404"}`, stderr `gh: Not Found (HTTP 404)`
+#   GraphQL miss  → rc 1, stdout `{"data":{…null…},"errors":[{"type":"NOT_FOUND",…}]}`
+
+PB_GH_TIMEOUT="${PB_GH_TIMEOUT:-60}"
+PB_GH_ATTEMPTS="${PB_GH_ATTEMPTS:-3}"
+PB_GH_BACKOFF="${PB_GH_BACKOFF:-2 4 8}"
+# Exit code the watchdog reports for a killed command (mirrors GNU timeout).
+PB_GH_RC_TIMEOUT=124
+
+# pb_run_with_timeout SECONDS OUT ERR CMD... -> CMD's exit code, or 124 when
+# the watchdog killed it. stdout/stderr go to the OUT/ERR files.
+pb_run_with_timeout() {
+  local secs="$1" out="$2" err="$3"; shift 3
+  local rcfile wdfile pid watchdog sleeper rc
+  rcfile=$(mktemp "${PB_TMPDIR:-${TMPDIR:-/tmp}}/pb-rc.XXXXXX") || return 1
+  wdfile="$rcfile.wd"
+  : >"$rcfile"; : >"$wdfile"
+  # `set +e` inside: the caller's errexit would otherwise end the subshell
+  # before the exit code is recorded, and an empty rc file reads as a timeout.
+  (
+    set +e
+    "$@" >"$out" 2>"$err"
+    echo $? >"$rcfile"
+  ) &
+  pid=$!
+  # The watchdog detaches from the caller's stdio and publishes its sleeper's
+  # pid: killing only the subshell would orphan `sleep`, which then holds any
+  # pipe the caller (bats, a `$(...)`) is waiting on until the timeout elapses.
+  (
+    sleep "$secs" &
+    echo $! >"$wdfile"
+    wait $!
+    kill "$pid" 2>/dev/null
+  ) >/dev/null 2>&1 &
+  watchdog=$!
+  # Every wait/kill below may legitimately fail (job already gone, watchdog
+  # killed → wait returns 143); callers run under `set -e`, so none of them
+  # may be a bare statement.
+  wait "$pid" 2>/dev/null || true
+  sleeper=$(cat "$wdfile" 2>/dev/null || true)
+  [ -z "$sleeper" ] || kill "$sleeper" 2>/dev/null || true
+  kill "$watchdog" 2>/dev/null || true
+  wait "$watchdog" 2>/dev/null || true
+  rc=$(cat "$rcfile" 2>/dev/null || true)
+  rm -f "$rcfile" "$wdfile"
+  if [ -z "$rc" ]; then
+    echo "pr-babysit: timed out after ${secs}s: $*" >>"$err"
+    return "$PB_GH_RC_TIMEOUT"
+  fi
+  return "$rc"
+}
+
+# pb_gh_classify RC ERR_FILE OUT_FILE -> prints transient | permanent | ok.
+pb_gh_classify() {
+  local rc="$1" err="$2" out="$3" text status
+  [ "$rc" -eq 0 ] && { echo ok; return 0; }
+  [ "$rc" -eq "$PB_GH_RC_TIMEOUT" ] && { echo transient; return 0; }
+  # `set -e` callers: every pipeline that may match nothing ends in `|| true`.
+  text=$( { cat "$err" 2>/dev/null; cat "$out" 2>/dev/null; } || true)
+  # HTTP status: gh prints "(HTTP NNN)" on stderr; REST bodies carry "status".
+  status=$(printf '%s' "$text" | grep -oE '\(HTTP [0-9]{3}\)' | head -1 | tr -dc '0-9' || true)
+  [ -n "$status" ] || status=$(jq -r '.status? // empty' "$out" 2>/dev/null | head -1 || true)
+  case "$status" in
+    5??|429) echo transient; return 0 ;;
+    403)
+      if printf '%s' "$text" | grep -qi 'rate limit'; then echo transient; else echo permanent; fi
+      return 0 ;;
+    4??) echo permanent; return 0 ;;
+  esac
+  if printf '%s' "$text" | grep -qiE 'connection refused|connection reset|no such host|i/o timeout|TLS handshake|unexpected EOF|EOF$|network is unreachable|temporary failure|timed out'; then
+    echo transient; return 0
+  fi
+  # GraphQL errors[] without an HTTP status (NOT_FOUND etc.) are permanent.
+  if jq -e '.errors? | type == "array" and length > 0' "$out" >/dev/null 2>&1; then
+    echo permanent; return 0
+  fi
+  echo permanent
+}
+
+# pb_gh OUT_FILE ARGS... -> run `gh ARGS` with timeout + bounded retry.
+# 0 on success (OUT_FILE holds stdout). Non-zero after the policy is
+# exhausted or on a permanent error; sets PB_GH_ATTEMPTED, PB_GH_LAST_RC,
+# PB_GH_LAST_ERR (first stderr line), PB_GH_CLASS for the caller's error.
+pb_gh() {
+  local out="$1"; shift
+  local err attempt rc class delay i
+  err="$out.err"
+  PB_GH_ATTEMPTED=0; PB_GH_LAST_RC=0; PB_GH_LAST_ERR=""; PB_GH_CLASS=ok
+  attempt=0
+  while [ "$attempt" -lt "$PB_GH_ATTEMPTS" ]; do
+    attempt=$((attempt + 1))
+    PB_GH_ATTEMPTED=$attempt
+    rc=0
+    pb_run_with_timeout "$PB_GH_TIMEOUT" "$out" "$err" gh "$@" || rc=$?
+    class=$(pb_gh_classify "$rc" "$err" "$out")
+    PB_GH_LAST_RC=$rc; PB_GH_CLASS=$class
+    PB_GH_LAST_ERR=$(head -n 1 "$err" 2>/dev/null || true)
+    case "$class" in
+      ok) rm -f "$err"; return 0 ;;
+      permanent) return 1 ;;
+    esac
+    [ "$attempt" -lt "$PB_GH_ATTEMPTS" ] || break
+    i=0; delay=2
+    for delay in $PB_GH_BACKOFF; do
+      i=$((i + 1))
+      [ "$i" -eq "$attempt" ] && break
+    done
+    echo "pr-babysit: gh $1 attempt $attempt failed ($class: ${PB_GH_LAST_ERR:-rc $rc}); retrying in ${delay}s" >&2
+    sleep "$delay"
+  done
+  return 1
+}
+
+# pb_gh_json_ok FILE -> 0 when FILE parses and carries no GraphQL errors[].
+pb_gh_json_ok() {
+  jq -e 'type as $t | if $t == "object" then ((.errors? // []) | length) == 0 else true end' "$1" >/dev/null 2>&1
+}
+
+# pb_gh_fail SOURCE — emit api_error/invalid_json from the last pb_gh state
+# and exit 3. SOURCE names the read that failed (pr, threads, comments, …).
+pb_gh_fail() {
+  local source="$1" code=api_error
+  [ "${PB_GH_CLASS:-}" = invalid_json ] && code=invalid_json
+  pb_fail "$code" "gh ${source} failed after ${PB_GH_ATTEMPTED:-0} attempt(s): ${PB_GH_LAST_ERR:-rc ${PB_GH_LAST_RC:-?}}" \
+    "$(jq -nc --arg source "$source" --argjson attempts "${PB_GH_ATTEMPTED:-0}" \
+        --arg class "${PB_GH_CLASS:-}" --arg lastMessage "${PB_GH_LAST_ERR:-}" \
+        '{source:$source, attempts:$attempts, class:$class, lastMessage:$lastMessage}')"
+}

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

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# lock.sh — one-writer lock per slot state file.
+#
+# Sourced after common.sh. `mkdir` is atomic on every POSIX filesystem, so the
+# lock is a directory beside the state file: <state-file>.lock/ holding `pid`
+# and `since` (epoch seconds). Atomic rename alone does not stop two
+# controllers from losing each other's updates — this does. A lock whose pid is
+# dead or older than PB_LOCK_STALE_SECONDS is stale and reclaimed with a stderr
+# note. Release is wired through pb_on_exit (common.sh) so a crash or signal
+# never leaves a live lock behind.
+
+PB_LOCK_STALE_SECONDS="${PB_LOCK_STALE_SECONDS:-600}"
+PB_LOCK_DIR=""
+# The lock dir this process is trying to take. A signal can land between
+# `mkdir` succeeding and PB_LOCK_DIR being set; pb_lock_release uses this to
+# recognise (and remove) such a half-written lock of its own on exit.
+PB_LOCK_WANT=""
+PB_LOCK_HOLDER_PID=""
+PB_LOCK_HOLDER_SINCE=""
+
+# pb_lock_path STATE_FILE -> the lock directory path.
+pb_lock_path() { printf '%s.lock' "$1"; }
+
+# _pb_lock_stale LOCKDIR -> 0 when the holder is dead or too old.
+_pb_lock_stale() {
+  local lockdir="$1" pid since now
+  pid=$(cat "$lockdir/pid" 2>/dev/null || echo "")
+  since=$(cat "$lockdir/since" 2>/dev/null || echo "")
+  now=$(date +%s)
+  # A lock dir with no pid/since is a half-written lock from a crashed taker.
+  [ -n "$pid" ] && [ -n "$since" ] || return 0
+  case "$pid$since" in *[!0-9]*) return 0 ;; esac
+  if ! kill -0 "$pid" 2>/dev/null; then return 0; fi
+  [ $((now - since)) -gt "$PB_LOCK_STALE_SECONDS" ] && return 0
+  return 1
+}
+
+# pb_lock_acquire STATE_FILE -> 0 and PB_LOCK_DIR set; 75 when a live holder
+# owns it (PB_LOCK_HOLDER_PID/SINCE describe it). Reclaims a stale lock once.
+pb_lock_acquire() {
+  local state_file="$1" lockdir attempt
+  lockdir=$(pb_lock_path "$state_file")
+  mkdir -p "$(dirname "$state_file")" || return 1
+  PB_LOCK_WANT="$lockdir"
+  for attempt in 1 2; do
+    if mkdir "$lockdir" 2>/dev/null; then
+      PB_LOCK_DIR="$lockdir"
+      printf '%s\n' "$$" >"$lockdir/pid"
+      date +%s >"$lockdir/since"
+      return 0
+    fi
+    PB_LOCK_HOLDER_PID=$(cat "$lockdir/pid" 2>/dev/null || echo "")
+    PB_LOCK_HOLDER_SINCE=$(cat "$lockdir/since" 2>/dev/null || echo "")
+    if [ "$attempt" -eq 1 ] && _pb_lock_stale "$lockdir"; then
+      echo "pr-babysit: reclaiming stale lock $lockdir (pid ${PB_LOCK_HOLDER_PID:-?}, since ${PB_LOCK_HOLDER_SINCE:-?})" >&2
+      rm -rf "$lockdir"
+      continue
+    fi
+    return 75
+  done
+  return 75
+}
+
+# pb_lock_release — remove the lock only if this process took it.
+pb_lock_release() {
+  if [ -n "$PB_LOCK_DIR" ]; then
+    if [ "$(cat "$PB_LOCK_DIR/pid" 2>/dev/null)" = "$$" ]; then
+      rm -rf "$PB_LOCK_DIR"
+    fi
+  elif [ -n "$PB_LOCK_WANT" ] && [ -d "$PB_LOCK_WANT" ] && [ ! -e "$PB_LOCK_WANT/pid" ]; then
+    # mkdir succeeded but a signal arrived before the pid was written: the
+    # dir is ours and empty — take it back rather than leave a stale lock.
+    rm -rf "$PB_LOCK_WANT"
+  fi
+  PB_LOCK_DIR=""; PB_LOCK_WANT=""
+  return 0
+}
+
+# pb_lock_fail STATE_FILE — emit the structured `locked` error and exit 75.
+pb_lock_fail() {
+  pb_fail locked "slot is held by another controller" \
+    "$(jq -nc --arg pid "$PB_LOCK_HOLDER_PID" --arg since "$PB_LOCK_HOLDER_SINCE" \
+        '{pid:($pid|tonumber? // null), since:($since|tonumber? // null)}')"
+}