@biffo/cli 0.236.0 → 0.237.0

package/_skeletons/plugin-template/AGENTS.md

@@ -48,7 +48,7 @@ This file is distributed by the template and kept in step by
 **Before starting work on an issue, run:**
 
 ```bash
-sh scripts/claim.sh <issue-number> [-R owner/repo]   # 0 free · 1 taken · 2 cannot tell
+sh scripts/biffo.sh claim <issue-number> [-R owner/repo]   # 0 free · 1 taken · 2 cannot tell
 ```
 
 Several agent sessions run against this estate at once. The script asks four
@@ -127,7 +127,25 @@ it deliberately and say so in a comment; never steal a fresh one.
   before merge: `git log origin/<branch> -1`. A green PR page is not proof your
   latest local commit reached it.
 
-## 7. Creating this repo correctly (read once, at birth)
+## 7. Verify post-merge
+
+- A merge is not done when the PR closes. **Check the whole branch:**
+
+  ```bash
+  sh scripts/biffo.sh branch-health [-R owner/repo]   # 0 green · 1 red · 2 cannot tell
+  ```
+
+  It reports the latest run of **every** workflow on the integration branch, so
+  the deploy cannot fall off the bottom of a short `gh run list` — and when
+  something is red it names the **first** failing commit, not the newest.
+
+- **Check whether the branch was already failing before diagnosing your own
+  change.** A red deploy has no audience: the author who broke it has moved on,
+  and every later merge fails on damage it did not cause. On 2026-08-02 that
+  cost 2h25m and four people each diagnosed their own innocent change.
+- Exit 2 is "cannot tell" and is never a pass.
+
+## 8. Creating this repo correctly (read once, at birth)
 
 **No `biffo` command creates a standalone plugin repo.** `biffo plugin create`
 scaffolds a plugin _into an existing checkout_; a repo like this one is made by
@@ -159,7 +177,7 @@ biffo check branch-protection --repo <org>/<repo>
 > that means merging with checks still running. Steps 1 and 2 together are what
 > make the documented flow behave as documented; either alone is not enough.
 
-## 8. CI runners — two steps this repo cannot do for itself
+## 9. CI runners — two steps this repo cannot do for itself
 
 The workflows use `runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}`, so they
 work anywhere by default and route to a self-hosted fleet when one exists. Two
@@ -176,7 +194,7 @@ fleet:
 If a job is queued and nothing is happening, check the grant before anything
 else. It is the failure that looks exactly like patience.
 
-## 9. Security
+## 10. Security
 
 - **Never commit secrets** (keys, tokens, credentials, `.env` values).
 - **Never silently disable a security gate.** If one must be loosened, do it in

package/_skeletons/sibling-template/AGENTS.md

@@ -48,7 +48,7 @@ This file is distributed by the template and kept in step by
 **Before starting work on an issue, run:**
 
 ```bash
-sh scripts/claim.sh <issue-number> [-R owner/repo]   # 0 free · 1 taken · 2 cannot tell
+sh scripts/biffo.sh claim <issue-number> [-R owner/repo]   # 0 free · 1 taken · 2 cannot tell
 ```
 
 Several agent sessions run against this estate at once. The script asks four
@@ -127,7 +127,25 @@ it deliberately and say so in a comment; never steal a fresh one.
   before merge: `git log origin/<branch> -1`. A green PR page is not proof your
   latest local commit reached it.
 
-## 7. Security
+## 7. Verify post-merge
+
+- A merge is not done when the PR closes. **Check the whole branch:**
+
+  ```bash
+  sh scripts/biffo.sh branch-health [-R owner/repo]   # 0 green · 1 red · 2 cannot tell
+  ```
+
+  It reports the latest run of **every** workflow on the integration branch, so
+  the deploy cannot fall off the bottom of a short `gh run list` — and when
+  something is red it names the **first** failing commit, not the newest.
+
+- **Check whether the branch was already failing before diagnosing your own
+  change.** A red deploy has no audience: the author who broke it has moved on,
+  and every later merge fails on damage it did not cause. On 2026-08-02 that
+  cost 2h25m and four people each diagnosed their own innocent change.
+- Exit 2 is "cannot tell" and is never a pass.
+
+## 8. Security
 
 - **Never commit secrets** (keys, tokens, credentials, `.env` values).
 - **Never silently disable a security gate.** If one must be loosened, do it in

package/dist/index.js

@@ -10770,7 +10770,7 @@ function resolveGithubToken4() {
   );
 }
 
-// src/commands/wait-for-checks.ts
+// src/lib/packaged-script-command.ts
 import { spawnSync } from "child_process";
 import { dirname as dirname11 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
@@ -10794,22 +10794,45 @@ function packagedScriptMissing(relativePath) {
 It ships with this package via cli/scripts/packaged-root-assets.mjs; if you are running from a checkout, run from inside the template repo. If you are running the published package, this is a packaging bug \u2014 the asset was not copied at prepack.`;
 }
 
-// src/commands/wait-for-checks.ts
-var SCRIPT = "scripts/wait-for-checks.sh";
-var waitForChecksCommand = new Command26("wait-for-checks").description(
-  "Wait for a PR\u2019s required checks on a positive signal (0 green, 1 failed, 2 cannot tell)"
-).argument("<pr>", "Pull request number").allowExcessArguments(true).allowUnknownOption(true).action(() => {
-  const here = dirname11(fileURLToPath6(import.meta.url));
-  const script = findPackagedScript(here, SCRIPT);
-  if (!script) {
-    process.stderr.write(`${packagedScriptMissing(SCRIPT)}
+// src/lib/packaged-script-command.ts
+function packagedScriptCommand(spec) {
+  const command = new Command26(spec.name).description(spec.description).allowExcessArguments(true).allowUnknownOption(true);
+  if (spec.argument) command.argument(`<${spec.argument.name}>`, spec.argument.description);
+  return command.action(() => {
+    const here = dirname11(fileURLToPath6(import.meta.url));
+    const script = findPackagedScript(here, spec.script);
+    if (!script) {
+      process.stderr.write(`${packagedScriptMissing(spec.script)}
 `);
-    process.exit(2);
-  }
-  const at = process.argv.indexOf("wait-for-checks");
-  const args = at === -1 ? [] : process.argv.slice(at + 1);
-  const result = spawnSync("sh", [script, ...args], { stdio: "inherit" });
-  process.exit(result.status === null ? 2 : result.status);
+      process.exit(2);
+    }
+    const at = process.argv.indexOf(spec.name);
+    const args = at === -1 ? [] : process.argv.slice(at + 1);
+    const result = spawnSync("sh", [script, ...args], { stdio: "inherit" });
+    process.exit(result.status === null ? 2 : result.status);
+  });
+}
+
+// src/commands/branch-health.ts
+var branchHealthCommand = packagedScriptCommand({
+  name: "branch-health",
+  script: "scripts/branch-health.sh",
+  description: "Report every workflow on the integration branch (0 green, 1 red, 2 cannot tell)"
+});
+
+// src/commands/claim.ts
+var claimCommand = packagedScriptCommand({
+  name: "claim",
+  script: "scripts/claim.sh",
+  description: "Check and claim an issue before starting (0 free, 1 taken, 2 cannot tell)"
+});
+
+// src/commands/wait-for-checks.ts
+var waitForChecksCommand = packagedScriptCommand({
+  name: "wait-for-checks",
+  script: "scripts/wait-for-checks.sh",
+  description: "Wait for a PR\u2019s required checks on a positive signal (0 green, 1 failed, 2 cannot tell)",
+  argument: { name: "pr", description: "Pull request number" }
 });
 
 // src/index.ts
@@ -10827,6 +10850,8 @@ program.addCommand(deployCommand);
 program.addCommand(destroyCommand);
 program.addCommand(teardownCommand);
 program.addCommand(waitForChecksCommand);
+program.addCommand(branchHealthCommand);
+program.addCommand(claimCommand);
 program.addCommand(pluginCommand);
 program.addCommand(dataCommand);
 program.addCommand(coreCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.236.0",
+  "version": "0.237.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,9 @@
     "dist",
     "schemas",
     "_skeletons",
-    "scripts/wait-for-checks.sh"
+    "scripts/wait-for-checks.sh",
+    "scripts/branch-health.sh",
+    "scripts/claim.sh"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",

package/_skeletons/sibling-template/scripts/branch-health.sh

@@ -1,306 +0,0 @@
-#!/usr/bin/env bash
-#
-# Is the integration branch actually healthy — including the deploy, and
-# including who broke it?
-#
-# ## Why this exists
-#
-# On 2026-08-02 an instance's `dev` deploy went red at 10:43 and nobody noticed
-# until 12:36. **1h53m, four further merges**, each of which also failed, and
-# development was effectively blocked for 2h25m. Three separate things had to be
-# true at once for that to happen, and this script answers all three (#1133).
-#
-# **1. The obvious command hides the deploy.** An instance runs five workflows on
-# a merge to `dev` — `CI`, `CodeQL`, `Core Version Tag`, `Deploy Application`,
-# `RLS Tests` — and the reflexive check is:
-#
-#     gh run list --branch dev --limit 3
-#
-# which returns three that are *not* the deploy. "dev CI green" was reported
-# truthfully and repeatedly by an agent following AGENTS.md, while the deploy was
-# red the whole time. A truncated list is not a status; it is a sample. This
-# script enumerates **every** workflow that ran on the branch and reports the
-# latest conclusion of each, so nothing can fall off the bottom.
-#
-# **2. A red post-merge deploy has no audience.** A failing PR check is noticed
-# because someone is watching their PR. A failing *post-merge* deploy is watched
-# by nobody: the author has moved on, and the next person only discovers it by
-# merging into it. So this notifies, reusing the desktop-alert channel
-# `practices-daily.sh` established (`_notify`) — same opt-OUT posture, because an
-# opt-in alert is how that notification once spent months existing and never
-# firing.
-#
-# **3. A poisoned branch blames the wrong person.** Once `dev` is broken every
-# subsequent merge fails too, so four people each saw *their* change fail. The
-# expensive part was not the breakage, it was four independent diagnoses of an
-# innocent change. On failure this walks the run history back to the **first
-# failing run** and names its commit, author and time — so the fifth person in
-# starts at the real cause instead of their own diff.
-#
-# ## Exit codes
-#
-#   0  every workflow observed on the branch concluded, none failed
-#   1  something failed — the workflow names and the first bad commit are printed
-#   2  cannot determine: no runs found, or the repo/branch is unreadable
-#
-# 2 is deliberately not 0, matching `wait-for-checks.sh` and `ci-wiring-audit.sh`.
-# A check that cannot see its input must say so rather than passing: this
-# estate's most repeated defect is a zero that means "could not look", and
-# `protection-audit.sh` was reporting `27 branches, all protected` while silently
-# dropping the four repos least likely to be protected (#1145).
-#
-# `cancelled` is reported but does not fail the branch. On self-hosted runners it
-# is usually spot reclamation or a `cancel-in-progress` concurrency group — two
-# merges landing seconds apart cancel the first run by design. It is called out
-# by name so nobody debugs a phantom.
-#
-# ## Usage
-#
-#   sh scripts/branch-health.sh [-R owner/repo] [--branch dev] [--quiet]
-#
-# Requires `gh`, authenticated. Uses gh's embedded jq, so no jq binary is needed.
-
-set -uo pipefail
-
-REPO=""
-BRANCH=""
-QUIET=""
-
-usage() {
-  sed -n '2,60p' "$0" | sed 's/^# \{0,1\}//'
-  exit 2
-}
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    -R | --repo)
-      REPO="${2:-}"
-      shift 2
-      ;;
-    --branch)
-      BRANCH="${2:-}"
-      shift 2
-      ;;
-    --quiet)
-      QUIET=1
-      shift
-      ;;
-    -h | --help) usage ;;
-    *)
-      echo "branch-health: unexpected argument '$1'" >&2
-      usage
-      ;;
-  esac
-done
-
-RED=$(printf '\033[31m')
-GREEN=$(printf '\033[32m')
-YELLOW=$(printf '\033[33m')
-DIM=$(printf '\033[90m')
-OFF=$(printf '\033[0m')
-
-# A real tab, built the same way the colours above are, and used as `IFS="$TAB"`.
-#
-# AGENTS.md invokes these scripts as `sh scripts/...`, and /bin/sh is dash here.
-# The bash spelling `IFS=$'\t'` is NOT a syntax error under dash — it is read as
-# the four literal characters `$ ' \ t`, so the field split then happens on any
-# of them. The first draft of this script did exactly that and reported a
-# workflow called "Deploy Applica", having split "Deploy Application" at its
-# 't'. It printed one row instead of four and still exited 0.
-#
-# Same reason the colours use `$(printf '\033[31m')` rather than `$'\e[31m'`.
-TAB=$(printf '\t')
-
-gh_run() {
-  if [ -n "$REPO" ]; then gh run "$@" --repo "$REPO"; else gh run "$@"; fi
-}
-
-# The integration branch is `dev` in every Biffo repo (AGENTS.md §2). Resolved
-# from the repo rather than hardcoded so this still works in the rare repo whose
-# default has not been migrated — and so the failure is "cannot read repo"
-# rather than a confident answer about a branch that does not exist.
-if [ -z "$BRANCH" ]; then
-  if [ -n "$REPO" ]; then
-    BRANCH=$(gh repo view "$REPO" --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null)
-  else
-    BRANCH=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null)
-  fi
-fi
-
-if [ -z "$BRANCH" ]; then
-  echo "${RED}branch-health: cannot determine the integration branch.${OFF}" >&2
-  exit 2
-fi
-
-label=${REPO:-$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")}
-
-# --- Every workflow that ran on the branch, not the first three --------------
-#
-# 200 runs is deep enough to reach every workflow's latest run even when a busy
-# one (CI) dominates the head of the list. `--json` on `gh run list` returns them
-# newest-first, so the first row per workflow name IS its latest run.
-
-# `group_by | max_by(.createdAt)` rather than "first occurrence in a newest-first
-# list": the ordering is gh's to change, and a status tool that quietly reports
-# an older run because an API changed its sort is the same class of defect as the
-# truncated list this replaces. Ask for the newest explicitly.
-summary=$(gh_run list --branch "$BRANCH" --limit 200 \
-  --json workflowName,status,conclusion,headSha,createdAt,url \
-  --jq 'group_by(.workflowName)
-        | map(max_by(.createdAt))
-        | .[]
-        | [ (if .status == "completed" then (.conclusion // "unknown") else .status end),
-            .workflowName, .headSha[0:8], .createdAt[0:16], .url ]
-        | @tsv' 2>/dev/null)
-
-if [ -z "$summary" ]; then
-  echo "${RED}branch-health: no workflow runs readable on '$BRANCH' in $label.${OFF}" >&2
-  echo "${DIM}  That is 'cannot tell', not 'healthy' — exiting 2.${OFF}" >&2
-  exit 2
-fi
-
-failed=""
-pending=""
-cancelled=""
-skipped=""
-ok=""
-
-while IFS="$TAB" read -r state name sha when url; do
-  [ -n "$name" ] || continue
-  case "$state" in
-    success) ok="${ok}${name}\n" ;;
-    failure | timed_out | startup_failure)
-      failed="${failed}${state}\t${name}\t${sha}\t${when}\t${url}\n"
-      ;;
-    cancelled) cancelled="${cancelled}${name}\n" ;;
-    skipped) skipped="${skipped}${name}\n" ;;
-    *) pending="${pending}${state}\t${name}\n" ;;
-  esac
-done <<EOF
-$summary
-EOF
-
-# --- Report -------------------------------------------------------------------
-
-echo "${DIM}$label — branch '$BRANCH', latest run per workflow${OFF}"
-echo
-
-# `printf '%b'` FIRST, then sed. These lists are accumulated as strings holding
-# literal `\n` two-character sequences (POSIX sh has no clean way to append a
-# real newline to a variable), so piping them straight to sed hands it a single
-# line and only the first entry gets its prefix — which read as a workflow with
-# no status at all. Expand the escapes, then prefix each real line.
-[ -n "$ok" ] && printf '%b' "$ok" | sed "s/^/  ${GREEN}ok${OFF}         /"
-[ -n "$skipped" ] && printf '%b' "$skipped" | sed "s/^/  ${DIM}skipped${OFF}    /"
-[ -n "$cancelled" ] && printf '%b' "$cancelled" | sed "s/^/  ${YELLOW}cancelled${OFF}  /"
-
-if [ -n "$pending" ]; then
-  printf '%b' "$pending" | awk -F'\t' -v d="$YELLOW" -v o="$OFF" 'NF{printf "  %srunning%s    %s (%s)\n", d, o, $2, $1}'
-fi
-
-if [ -z "$failed" ]; then
-  if [ -n "$cancelled" ]; then
-    echo
-    echo "${DIM}A cancelled run is usually spot reclamation or a superseded concurrency${OFF}"
-    echo "${DIM}group, not the code. Re-run it rather than debugging it.${OFF}"
-  fi
-  echo
-  echo "${GREEN}Nothing on '$BRANCH' is failing.${OFF}"
-  exit 0
-fi
-
-echo
-printf '%b' "$failed" | awk -F'\t' -v r="$RED" -v o="$OFF" 'NF{printf "  %s%s%s  %s  at %s  %s\n", r, $1, o, $2, $3, $5}'
-
-# --- Who actually broke it ----------------------------------------------------
-#
-# The whole point of #1133's third defect. Walk this workflow's runs on this
-# branch backwards from the newest failure through consecutive failures, and
-# report the OLDEST one in that unbroken streak. That run's commit is where the
-# breakage started, which is very often not the person now reading this.
-
-echo
-printf '%b' "$failed" | while IFS="$TAB" read -r state name sha when url; do
-  [ -n "$name" ] || continue
-
-  # Sort newest-first ourselves, cut the list at the most recent SUCCESS, and
-  # take the oldest failure still inside that streak. Anything before a green run
-  # is a different, already-fixed breakage and must not be blamed for this one.
-  first=$(gh_run list --branch "$BRANCH" --workflow "$name" --limit 60 \
-    --json conclusion,headSha,createdAt,displayTitle,url \
-    --jq 'sort_by(.createdAt) | reverse
-          | (map(.conclusion == "success") | index(true)) as $green
-          | .[0: (if $green == null then length else $green end)]
-          | map(select(.conclusion == "failure"
-                    or .conclusion == "timed_out"
-                    or .conclusion == "startup_failure"))
-          | last
-          | select(. != null)
-          | [ .headSha[0:8], .createdAt[0:16], (.displayTitle // "")[0:72], .url ]
-          | @tsv' 2>/dev/null)
-
-  if [ -n "$first" ]; then
-    f_sha=$(printf '%s' "$first" | cut -f1)
-    f_when=$(printf '%s' "$first" | cut -f2)
-    f_title=$(printf '%s' "$first" | cut -f3)
-    f_url=$(printf '%s' "$first" | cut -f4)
-    echo "  ${RED}$name${OFF} has been failing since ${YELLOW}$f_sha${OFF} ($f_when)"
-    echo "    $f_title"
-    echo "    ${DIM}$f_url${OFF}"
-    if [ "$f_sha" != "$sha" ]; then
-      echo "    ${DIM}The newest failure is at $sha — but it is NOT where this started.${OFF}"
-      echo "    ${DIM}Diagnose $f_sha, not your own merge.${OFF}"
-    fi
-  else
-    echo "  ${RED}$name${OFF} is failing at $sha ${DIM}(could not establish when it started)${OFF}"
-  fi
-done
-
-# --- Tell somebody ------------------------------------------------------------
-#
-# Copied in posture, deliberately, from practices-daily.sh's `_notify`: opt-OUT
-# via an env var rather than opt-in, because an opt-in alert is one that never
-# fires. Replaces its own previous card rather than stacking, so a branch red for
-# three days is one notification and not three.
-
-_notify() {
-  [ -z "$QUIET" ] || return 0
-  command -v notify-send >/dev/null 2>&1 || return 0
-  [ -z "${BRANCH_HEALTH_NO_DESKTOP_ALERT:-}" ] || return 0
-
-  if [ -z "${DBUS_SESSION_BUS_ADDRESS:-}" ]; then
-    _bus="/run/user/$(id -u)/bus"
-    [ -S "$_bus" ] || return 0
-    DBUS_SESSION_BUS_ADDRESS="unix:path=$_bus"
-    export DBUS_SESSION_BUS_ADDRESS
-  fi
-
-  _slug=$(printf '%s' "$label-$BRANCH" | tr -c 'a-zA-Z0-9' '-')
-  _idfile="${XDG_RUNTIME_DIR:-/tmp}/biffo-branch-health-${_slug}.id"
-  _prev=""
-  [ -f "$_idfile" ] && _prev=$(cat "$_idfile" 2>/dev/null)
-
-  # Built as a plain variable rather than `${_prev:+--replace-id="$_prev"}`.
-  # That form nests double quotes inside a parameter expansion, which dash
-  # refuses to parse — and because the script is run as `sh`, the failure lands
-  # at RUNTIME, after all the useful output has already printed, turning a
-  # correct exit 1 into a confusing exit 2.
-  _replace=""
-  [ -n "$_prev" ] && _replace="--replace-id=$_prev"
-
-  _names=$(printf '%b' "$failed" | awk -F'\t' 'NF{printf "%s ", $2}')
-  # Deliberately unquoted: empty must expand to no argument at all.
-  # shellcheck disable=SC2086
-  _new=$(notify-send --print-id $_replace \
-    -u critical -a "biffo" \
-    "$label: $BRANCH is red" \
-    "$_names— nobody is watching a post-merge failure. sh scripts/branch-health.sh" 2>/dev/null)
-  [ -n "$_new" ] && printf '%s' "$_new" > "$_idfile" 2>/dev/null
-  return 0
-}
-
-_notify
-
-echo
-echo "${RED}'$BRANCH' is red. It blocks everyone — fixing it is the next task (AGENTS.md §6).${OFF}"
-exit 1

package/_skeletons/sibling-template/scripts/claim.sh

@@ -1,208 +0,0 @@
-#!/usr/bin/env sh
-#
-# Is anyone already working this issue? Ask git, not a label.
-#
-# ## Why this exists
-#
-# Several agent sessions run against this estate at once, and on 2026-08-03
-# **four** of them collided in one morning:
-#
-#   - #1165 — another session built AND MERGED a PR for it while this one was
-#     claiming it. Three minutes, start to merge.
-#   - #1174 — a live worktree on `fix/1174-…` existed; the issue was unlabelled.
-#   - #621, #956 — live worktrees, no labels. Labelled on their behalf.
-#   - #1188 — the reverse: a label with no work, while another session built it
-#     and opened a PR.
-#
-# Three of the four were "work exists, label does not". That is the shape this
-# script is for.
-#
-# ## The rule it encodes
-#
-# **The `in-progress` label is a hand-maintained second copy of something git
-# already knows.** A branch exists. A PR exists. Those are automatic — you
-# cannot do the work without creating them — whereas the label is a separate
-# action a human or agent has to remember, in a workflow that may never have
-# been told to. Second copies of a decision drift; this estate says so about
-# `_extract_detail`, about AGENTS.md, and about the commit-msg type list.
-#
-# So this checks FOUR signals and reports all of them, rather than trusting the
-# one that is easiest to forget.
-#
-# ## What it cannot do
-#
-# Prevent a race. GitHub has no locking, two sessions can start in the same
-# second, and #1165 went from branch to merged in three minutes — no protocol
-# would have caught that. The goal is early, cheap detection, not exclusion.
-# Every collision that morning was caught before duplicate work merged; the
-# cost was minutes, not shipped rework.
-#
-# ## Usage
-#
-#   sh scripts/claim.sh 1234                 # check, and claim if free
-#   sh scripts/claim.sh 1234 --check         # report only, change nothing
-#   sh scripts/claim.sh 1234 -R owner/repo
-#
-#   0  free — and claimed, unless --check
-#   1  taken, or already closed — the reason is printed
-#   2  cannot tell — issue unreadable, gh unauthenticated
-#
-# 2 is deliberately not 0, matching `wait-for-checks.sh` and `branch-health.sh`.
-# A check that cannot see its input must not report "free".
-#
-# Requires `gh`, authenticated. Uses gh's embedded jq, so no jq binary needed.
-
-set -u
-
-ISSUE=""
-REPO=""
-CHECK_ONLY=""
-
-usage() {
-  sed -n '2,58p' "$0" | sed 's/^# \{0,1\}//'
-  exit 2
-}
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    -R | --repo)
-      REPO="${2:-}"
-      shift 2
-      ;;
-    --check) CHECK_ONLY=1; shift ;;
-    -h | --help) usage ;;
-    *)
-      ISSUE="$1"
-      shift
-      ;;
-  esac
-done
-
-case "$ISSUE" in
-  '' | *[!0-9]*)
-    echo "claim: give an issue number, e.g. sh scripts/claim.sh 1234" >&2
-    exit 2
-    ;;
-esac
-
-RED=$(printf '\033[31m')
-GREEN=$(printf '\033[32m')
-YELLOW=$(printf '\033[33m')
-DIM=$(printf '\033[90m')
-OFF=$(printf '\033[0m')
-
-gh_issue() { if [ -n "$REPO" ]; then gh issue "$@" --repo "$REPO"; else gh issue "$@"; fi; }
-gh_pr() { if [ -n "$REPO" ]; then gh pr "$@" --repo "$REPO"; else gh pr "$@"; fi; }
-
-LABEL=in-progress
-TAKEN=0
-REASONS=""
-
-note() { REASONS="${REASONS}  $1\n"; TAKEN=1; }
-
-# --- 0. Does the issue exist, and is it still open? --------------------------
-
-meta=$(gh_issue view "$ISSUE" --json state,title,labels \
-  --jq '"\(.state)\t\(.title)\t\((.labels|map(.name)|join(",")))"' 2>/dev/null) || {
-  echo "${RED}claim: cannot read issue #$ISSUE${OFF} — wrong repo, or gh not authenticated." >&2
-  echo "${DIM}  That is 'cannot tell', not 'free'.${OFF}" >&2
-  exit 2
-}
-
-state=$(printf '%s' "$meta" | cut -f1)
-title=$(printf '%s' "$meta" | cut -f2)
-labels=$(printf '%s' "$meta" | cut -f3)
-
-echo "${DIM}#$ISSUE — $title${OFF}"
-echo
-
-if [ "$state" != "OPEN" ]; then
-  echo "${RED}Already $state.${OFF} Nothing to claim."
-  exit 1
-fi
-
-# --- 1. The label. Easiest to check, easiest to forget. ----------------------
-
-case ",$labels," in
-  *",$LABEL,"*)
-    updated=$(gh_issue view "$ISSUE" --json updatedAt --jq .updatedAt 2>/dev/null)
-    note "${YELLOW}label${OFF}      carries '$LABEL' (issue last updated $updated)"
-    ;;
-esac
-
-# --- 2. An open PR that references it ----------------------------------------
-#
-# The strongest signal, because a PR cannot be opened without the work existing.
-# Matches the issue number in the title or body as a whole number, so #118 does
-# not match #1188.
-
-open_prs=$(gh_pr list --state open --limit 100 --json number,title,body,headRefName \
-  --jq "[.[] | select(((.title + \" \" + .body) | test(\"(^|[^0-9])#$ISSUE([^0-9]|\$)\")) or (.headRefName | test(\"(^|[^0-9])$ISSUE([^0-9]|\$)\")))] | .[] | \"#\(.number) \(.headRefName)\"" 2>/dev/null)
-
-if [ -n "$open_prs" ]; then
-  printf '%s\n' "$open_prs" | while IFS= read -r pr; do
-    [ -n "$pr" ] && echo "  ${RED}open PR${OFF}    $pr"
-  done
-  note "${RED}open PR${OFF}    see above — someone has working code"
-fi
-
-# --- 3. A remote branch naming it --------------------------------------------
-#
-# Catches work that has been pushed but has no PR yet. Whole-number match again.
-
-branches=$(git ls-remote --heads "${REPO:+https://github.com/$REPO.git}" 2>/dev/null |
-  sed 's|.*refs/heads/||' |
-  grep -E "(^|[^0-9])$ISSUE([^0-9]|$)" 2>/dev/null)
-
-if [ -n "$branches" ]; then
-  printf '%s\n' "$branches" | while IFS= read -r b; do
-    [ -n "$b" ] && echo "  ${RED}branch${OFF}     $b"
-  done
-  note "${RED}branch${OFF}     a remote branch names this issue"
-fi
-
-# --- 4. A recently merged PR that already closed it --------------------------
-#
-# Not "taken" — "possibly already done". #1165 was built and merged in three
-# minutes; the only trace afterwards is a merged PR.
-
-merged=$(gh_pr list --state merged --limit 30 --json number,title,body,mergedAt \
-  --jq "[.[] | select((.title + \" \" + .body) | test(\"(^|[^0-9])#$ISSUE([^0-9]|\$)\"))] | .[0] | select(. != null) | \"#\(.number) merged \(.mergedAt[0:16])\"" 2>/dev/null)
-
-if [ -n "$merged" ]; then
-  echo "  ${YELLOW}merged${OFF}     $merged"
-  echo "  ${DIM}           the issue is still open, but work referencing it has landed —${OFF}"
-  echo "  ${DIM}           read it before rebuilding.${OFF}"
-fi
-
-# --- Verdict ------------------------------------------------------------------
-
-echo
-if [ "$TAKEN" -eq 1 ]; then
-  printf '%b' "${RED}Taken.${OFF} Signals:\n$REASONS"
-  echo
-  echo "${DIM}If you believe it is abandoned, check how old the work is and say so in a${OFF}"
-  echo "${DIM}comment before taking it. Never steal a fresh claim.${OFF}"
-  exit 1
-fi
-
-if [ -n "$CHECK_ONLY" ]; then
-  echo "${GREEN}Free.${OFF} ${DIM}(--check: nothing changed)${OFF}"
-  exit 0
-fi
-
-# Claim it. Label AND comment together: the label is what other sessions filter
-# on, the comment is what dates it so a stale claim can be recognised later.
-gh_issue edit "$ISSUE" --add-label "$LABEL" >/dev/null 2>&1 || {
-  echo "${RED}claim: could not apply the '$LABEL' label.${OFF}" >&2
-  echo "${DIM}  Not claimed. Do not start work on the assumption that it worked.${OFF}" >&2
-  exit 2
-}
-gh_issue comment "$ISSUE" \
-  --body "Claimed at $(date -u +%FT%TZ) by \`$(git config user.name 2>/dev/null || echo agent)\`. Release it — remove the label — on merge, or if you stop." \
-  >/dev/null 2>&1
-
-echo "${GREEN}Claimed.${OFF}"
-echo "${DIM}Push your branch as soon as it exists: a claim is a reservation, the branch${OFF}"
-echo "${DIM}is the evidence, and the window between them is where collisions happen.${OFF}"
-exit 0