@plot-pm/board 0.10.0 → 0.12.0

package/plot-host.sh

@@ -14,12 +14,39 @@
 #                                    "draft":true|false,"url":"..."}
 #                                 NONE = no PR found (exit 0 — callers branch on
 #                                 state, not exit codes)
+#   pr-merged <branch>            has ANY PR for this branch merged? prints one
+#                                 word: merged|not-merged|unknown
+#                                 READS `mergedAt`, NEVER `state`: a merged PR
+#                                 reports CLOSED, so `state` would refuse every
+#                                 squash-merged branch — the whole population
+#                                 the callers of this question exist for. And
+#                                 never ancestry: squash-merge rewrites the
+#                                 commits, so the branch stays "ahead of main"
+#                                 forever and `merge-base --is-ancestor` can
+#                                 never clear it.
+#                                 ASKS ABOUT ANY PR, NOT THE NEWEST. Measured
+#                                 2026-08-27: three branches whose work was on
+#                                 main reported unlanded, each masked by a newer
+#                                 unmerged PR the fleet had opened itself on the
+#                                 already-merged branch.
+#                                 `unknown` IS ITS OWN ANSWER and exits 0 — a
+#                                 host that cannot be asked must not answer
+#                                 not-merged, because every caller of this is
+#                                 deciding whether to REMOVE something and
+#                                 silence is never permission. A call that
+#                                 failed outright still exits 3.
 #   pr-create --title T [--body B] [--base BR] [--head BR] [--draft]
 #                                 create a PR, print its URL
 #   pr-merge <number> [--squash] [--delete-branch]
 #   pr-ready <number>              take a PR out of draft
 #                                 merge the PR
 #   pr-list [--state open|merged|closed|all] [--limit N] [--rich]
+#                                 [--repo <owner/repo>] pins the list to ONE
+#                                 repository, exactly as pr-state and pr-merged
+#                                 do. A checkout with remotes on two hosts lets
+#                                 an unpinned list resolve the wrong one, and a
+#                                 caller joining it against `origin/*` refs then
+#                                 reads every branch as having no PR.
 #                                 JSON lines: {"number":N,"title":"...",
 #                                 "state":"...","head":"..."}
 #                                 --rich adds: draft, checks, mergeable, review,
@@ -35,6 +62,19 @@
 #                                 cannot answer reports (absent is not false)
 #                                 --limit raises the host CLI's default page of
 #                                 30, which --state all exhausts immediately
+#                                 THREE OUTCOMES, KEPT APART — the same rule
+#                                 issue-list states below, which this path
+#                                 collapsed until 2026-08-30. An empty list
+#                                 means the host answered and there are none
+#                                 (exit 0, no rows); a failed question exits
+#                                 non-zero with EMPTY stdout, never a silent
+#                                 empty list. EXIT 5 is a SPENT QUOTA, exit 6 a
+#                                 SECONDARY limit, and exit 3 any other
+#                                 failure. The three are separate because they
+#                                 ask for different responses: 5 says wait for
+#                                 the reset, 6 says retry shortly and lower
+#                                 concurrency, 3 says look. An unrecognised
+#                                 error is never given the more specific name.
 #   runs <branch> [--limit N]     a branch's own recent CI runs, newest first,
 #                                 as JSON lines: {"workflow":"CI",
 #                                 "conclusion":"success|failure|…",
@@ -48,13 +88,52 @@
 #                                 to be failing. Empty on bitbucket (bb has no
 #                                 run listing) — unavailable, never "never
 #                                 failed".
+#   run-for-sha <branch> <sha>    the run for ONE sha — else the branch's newest
+#                                 run, with `sha` saying which it is — as a
+#                                 single JSON object, or nothing when the branch
+#                                 has no runs at all:
+#                                   {"sha":"…","status":"queued|in_progress|
+#                                    completed|waiting|requested",
+#                                    "conclusion":"success|failure|…|null",
+#                                    "url":"…","startedAt":"…"}
+#                                 PINNED TO A SHA, which is the whole reason it
+#                                 exists beside `runs`. `runs` is branch-scoped
+#                                 and sha-blind, and `gh run list --branch X`
+#                                 returns runs for every sha that branch ever
+#                                 had — the newest run is NOT necessarily for
+#                                 the newest commit. A green answer read off the
+#                                 wrong run reports success for code nobody will
+#                                 merge, which is worse than no answer: it
+#                                 invites a merge of the wrong thing. Measured
+#                                 2026-08-30: two merge waiters reported on
+#                                 superseded runs and had to be stopped and
+#                                 re-armed.
+#                                 THE FALLBACK IS WHAT MAKES THAT VISIBLE. Were
+#                                 it to report nothing when the asked-for sha
+#                                 has no run, a run IN FLIGHT for a superseded
+#                                 commit would look exactly like no run at all,
+#                                 and a caller could not tell "CI has not
+#                                 started" from "CI is answering about the
+#                                 past". `sha` names the run's own commit, and
+#                                 comparing it to the one asked about is the
+#                                 CALLER's rule — this decides nothing.
+#                                 `status` AND `conclusion` ARE BOTH REPORTED,
+#                                 never collapsed. A run that is `completed` has
+#                                 a conclusion; one that is `waiting` or
+#                                 `action_required` has none yet, and folding
+#                                 the two would report a build blocked on a
+#                                 human click as merely pending forever.
+#                                 NOTHING on bitbucket (bb has no run listing) —
+#                                 unavailable, never "no run".
 #   issue-list [--limit N]        open tracker issues as JSON lines:
 #                                 {"number":N,"title":"…","url":"…",
 #                                  "createdAt":"…"}
-#                                 READ-ONLY, and the only issue op here: Plot
-#                                 never writes to the tracker (no labels, no
-#                                 assignees, no close-on-merge), because a copy
-#                                 of tracker state ages into a lie.
+#                                 READ-ONLY. Plot writes no label, no assignee
+#                                 and no close-on-merge, because a copy of
+#                                 tracker state ages into a lie. The one write
+#                                 that exists is `issue-status`, and it records
+#                                 a status Plot itself just caused rather than
+#                                 mirroring one the tracker holds.
 #                                 `url` is "" when the host omits it, and a
 #                                 consumer renders the number as plain text
 #                                 rather than inventing an address — the rule
@@ -86,8 +165,8 @@
 #                                 tickets*, the failure this story is named for.
 #   issue-view <number>           ONE open issue as a single JSON object:
 #                                 {"number":N,"title":"…","body":"…","url":"…"}
-#                                 STILL READ-ONLY — the second issue op, and it
-#                                 reads. The board's *Create plan* action needs
+#                                 READ-ONLY — the second of the two issue reads.
+#                                 The board's *Create plan* action needs
 #                                 the issue's BODY as the problem statement, and
 #                                 issue-list deliberately omits it: the list is
 #                                 asked on a timer for every open issue, and a
@@ -112,7 +191,84 @@
 #                                 as issue-list. Jira answers 404 for a missing
 #                                 key, which is exit 3 here (the tracker moved),
 #                                 never an empty body.
+#   issue-status <key> <status>   THE ONE WRITE TO A TRACKER: record one status
+#                                 against one issue, and nothing else. No
+#                                 create, no close, no comment, no label — a
+#                                 plan referencing an issue is Plot's record,
+#                                 and the status is the single fact the tracker
+#                                 owns a copy of.
+#                                 JIRA ONLY. Exit 4 where `Tracker` is not jira:
+#                                 this adapter cannot be asked, which is neither
+#                                 a failure nor a silent success. The other
+#                                 vendor's projects surface is written by
+#                                 `plot-update-board.sh`, under its own
+#                                 credentials and through a different API — the
+#                                 reason the tracker port has two connectors.
+#                                 Prints `written` where the transition was
+#                                 performed and `no-target` where the workflow
+#                                 offers no such transition from the issue's
+#                                 current state — which is also what a repeated
+#                                 write reports, because the same status twice
+#                                 is the same status.
+#                                 The transition id is LOOKED UP, never guessed:
+#                                 ids are per workflow and per issue, so a
+#                                 hardcoded one writes to the wrong column.
 #   pr-body <number> --body B     replace the PR description
+#   rate-limit                    both GitHub budgets from `gh api rate_limit`.
+#                                 SUPERSEDED BY `limit`, and kept only because
+#                                 its callers have not moved: that endpoint was
+#                                 measured 2026-09-01 reporting graphql
+#                                 5000/5000 used=0 while a real call's header
+#                                 read Remaining 1236, Used 3764, and reproduced
+#                                 2026-09-02 against a header's 2732. NOTHING
+#                                 ROUTES ON IT any more — `gh_route` reads the
+#                                 budget record, which is written from response
+#                                 headers. Prefer `limit`.
+#   limit                         what is this connector's limit, and how well
+#                                 does it know it? One JSON line per metered
+#                                 bucket: {"connector","bucket","limit",
+#                                 "remaining","reset","basis"} with `basis` one
+#                                 of actual|predicted|unknown, and the three
+#                                 numbers null where unreported. Reads the
+#                                 RESPONSE HEADERS of a real call, never
+#                                 `gh api rate_limit`. No output at all means
+#                                 this connector meters nothing — which is not
+#                                 the same fact as a limit of zero, and not
+#                                 `free` either.
+#   spend-rate [--connector C] [--account A] [--bucket B]
+#                                 what this COMPUTER has spent, read back from
+#                                 the record every spender appends to, as one
+#                                 JSON object: {"connector","account","bucket",
+#                                 "spent","spanMs","perHour","lines",
+#                                 "unreadable","limit","remaining","basis"}.
+#                                 AN OMITTED --bucket MEANS EVERY BUCKET, which
+#                                 is what "what am I spending?" asks: one
+#                                 connector meters several pools and an account
+#                                 spends all of them, so the cadence divides by
+#                                 the sum. A caller deciding whether a POOL is
+#                                 spent names it — `remaining` and `basis` in
+#                                 the aggregate describe whichever pool was
+#                                 spent last, which is a reading and not a
+#                                 verdict.
+#                                 OVER THE CONNECTOR'S WINDOW, never the whole
+#                                 file — ~1,160 lines an hour were measured
+#                                 2026-09-01, and a rate over an ever-growing
+#                                 span approaches zero. SPENDS NOTHING: it reads
+#                                 a file and asks no host. `perHour` is null
+#                                 where the window holds no span to divide by,
+#                                 which is an absent rate and never a zero one.
+#   ci-limit                      the same question of the CI connector, which
+#                                 is a separate axis: this repo is GitHub +
+#                                 Actions, ekzweb is Bitbucket + Jenkins.
+#                                 Jenkins reports no limit, so it answers
+#                                 `predicted`.
+#
+# TRANSPORT IS NOT A CALLER'S CONCERN. Where a host offers a question over more
+# than one transport — GitHub's REST against its GraphQL — the choice is made
+# inside this script, by `gh_route`, and no op reports which one answered. The
+# payload is identical either way by construction; a caller that could tell them
+# apart would start depending on the route. `PLOT_HOST_FORCE_REST=1` pins the
+# GitHub route to REST, and it is read in exactly one place.
 #
 # Backend resolution: $PLOT_HOST (github|bitbucket) wins — useful for tests —
 # else the `Git host` key from `## Plot Config` (via plot-config.sh), default
@@ -139,6 +295,133 @@ die() { echo "plot-host: $*" >&2; exit 1; }
 # error a person must fix, not a transient the board should retry past.
 die3() { echo "plot-host: $*" >&2; exit 3; }
 
+# Exit 5 — the host refused to answer FOR NOW. A rate limit, primary or
+# secondary: nothing is broken, nothing needs fixing, and the same question
+# asked later will be answered.
+#
+# ITS OWN CODE BECAUSE IT ASKS FOR A DIFFERENT RESPONSE. Exit 3 says *something
+# is wrong and a person must look*; this says *wait*. A caller that folded them
+# would counsel one when it meant the other, and the fleet scan's summary word
+# is exactly that choice made visible.
+#
+# NOT A RETRY, HERE OR ANYWHERE IN THIS ADAPTER. Whether to wait is the
+# caller's decision — a board on a 5 s cadence, a scan inside a 90 s budget and
+# a person at a terminal want three different answers — and a retry inside the
+# adapter would hide the very state this code exists to surface, turning a
+# reportable fact into an unexplained four-minute call.
+die5() { echo "plot-host: $*" >&2; exit 5; }
+
+# Exit 6 — the host refused because too many calls arrived AT ONCE. A secondary
+# limit, and a different ceiling from the one exit 5 reports.
+#
+# ITS OWN CODE BECAUSE THE TWO RECOVER DIFFERENTLY, which is the whole reason
+# this script now answers three words where it answered two. A spent quota
+# recovers at the reset the response carries — minutes away — and the honest
+# reaction is to stop until then and say when. A secondary limit clears in
+# seconds, carries no reset, and the reaction is to retry shortly and lower
+# concurrency. A caller told only *throttled* counsels one when it means the
+# other: it waits minutes for a limit that cleared, or it retries in seconds
+# into a bucket that is empty.
+#
+# BOTH WERE MEASURED HERE. 2026-08-27, eight workers against a cap of seven
+# produced a 403 naming abuse detection. 2026-09-01, `gh pr view` refused with
+# *"API rate limit already exceeded"* while the same account's GraphQL headers
+# read 4854 of 5000 remaining — a bucket with 97 % left does not refuse on
+# quota. So both causes are real, and the aggregate view could not tell them
+# apart.
+#
+# NOT A RETRY, for the reason exit 5 states: whether to wait is the caller's
+# decision, and this adapter reports rather than reacts.
+die6() { echo "plot-host: $*" >&2; exit 6; }
+
+# WHICH FAILURE, read off the wording — the same shape `bb_issue_exit_code`
+# uses, and for the same reason: the exit code cannot split these cases. `gh`
+# exits 1 for a rate limit and for a 503 alike, and puts the whole difference
+# in its stderr.
+#
+# THE SPLIT FALLS ONE WAY ONLY. An unrecognised error is never given the more
+# specific name. `throttled` counsels patience, and patience does not fix an
+# outage — so anything this does not recognise stays `failed`, which counsels
+# looking. That is the same direction `bb_issue_exit_code` refuses to guess in,
+# where an unrecognised error must be 3 rather than 4.
+#
+# THREE ANSWERS, BECAUSE THE TWO LIMITS ARE TWO CEILINGS. This returned
+# `throttled` for every match of one regex until 2026-09-02, so *"API rate
+# limit exceeded"* and *"You have exceeded a secondary rate limit"* came back
+# the same word and nothing downstream could tell them apart. `secondary` is
+# now its own answer: `die6` carries it, and the board names which limit was
+# hit rather than printing one reset over both.
+#
+# THE SECONDARY TEST RUNS FIRST, AND THE ORDER IS THE CLASSIFICATION. GitHub's
+# secondary message contains the phrase *"rate limit"* too — *"You have
+# exceeded a secondary rate limit"* — so a quota test applied first claims
+# every secondary refusal and the distinction is lost at the point it is made.
+host_failure_kind() { # $1=stderr text → throttled|secondary|failed
+  if LC_ALL=C grep -qiE 'secondary rate|exceeded a secondary|abuse detection|abuse-detection|too many requests|\b429\b' <<<"$1"; then
+    echo secondary
+  elif LC_ALL=C grep -qiE 'rate limit|ratelimit' <<<"$1"; then
+    echo throttled
+  else
+    echo failed
+  fi
+}
+
+# A failed `pr-list`, reported and never swallowed.
+#
+# THREE OUTCOMES, KEPT APART — the rule `issue-list` states in full and this
+# path collapsed until 2026-08-30. An empty list means the host answered and
+# there are none; a non-zero exit with empty stdout means the question failed.
+# Printing nothing while exiting non-zero is what says which.
+#
+# NO EMPTY-LIST FALLBACK, for the reason `issue-list` gives: `host_miss_or_fail`
+# exists for a lookup whose subject is absent — one PR that does not exist. A
+# LIST has no absent subject, so if the call failed, the answer is unknown.
+pr_list_failed() { # $1=stderr text
+  local err="$1"
+  case "$(host_failure_kind "$err")" in
+    secondary)
+      die6 "pr-list: host refused a burst — ${err:-the host refused the request and said nothing}"
+      ;;
+    throttled)
+      die5 "pr-list: host throttled — ${err:-the host refused the request and said nothing}"
+      ;;
+  esac
+  die3 "pr-list: ${err:-the host failed the request and said nothing}"
+}
+
+# Run one `pr-list` host call, or die reporting which failure it was.
+#
+# SIX CALL SITES SHARE THIS, and that is the point rather than a tidy-up.
+# `pr-list` branches on backend × rich × Jenkins into six separate invocations,
+# each of which had its own unchecked assignment; a fix applied by hand six
+# times is a fix that drifts, and the arm that drifts is the one nobody's repo
+# exercises. `plot-pr-merged.sh` makes the same argument for being sourced
+# rather than copied: two implementations of one gate fail toward permissive,
+# and permissive here means the silent empty list this exists to remove.
+#
+# The output goes to STDOUT for the caller to capture; only the error text is
+# spooled, because it is needed twice — once to classify and once to report.
+#
+# EVERY CALL SITE MUST WRITE `|| exit $?`, AND IT IS NOT OPTIONAL. This is
+# invoked as `_raw="$(pr_list_call …)"` — a COMMAND SUBSTITUTION, which is a
+# subshell — so the `exit` inside `die5`/`die3` leaves that subshell only. The
+# outer script would carry on with `_raw` empty and `jq` would emit nothing:
+# the silent empty list this whole helper exists to remove, rebuilt one layer
+# further in and harder to see. The same trap `bb_states_for` documents a few
+# hundred lines below, where a `die` in a subshell turned an unknown state into
+# "no PRs matched".
+pr_list_call() { # "$@"=the host command → payload on stdout, or dies
+  local out rc err tmp="/tmp/plot-host-prlist-err.$$"
+  out="$("$@" 2>"$tmp")"; rc=$?
+  err="$(cat "$tmp" 2>/dev/null)"; rm -f "$tmp"
+  [ "$rc" -eq 0 ] || pr_list_failed "$err"
+  # A non-empty stderr on a SUCCESSFUL call is a warning, not a verdict — `gh`
+  # writes deprecation notices there. Passed through so it is not lost, while
+  # the payload is still returned.
+  [ -n "$err" ] && echo "$err" >&2
+  printf '%s' "$out"
+}
+
 # --- Jenkins CI integration ------------------------------------------------
 # A repo may declare `CI: jenkins` independently of `Git host`. When it does,
 # build status (`checks`) is resolved through `jen` — a multibranch job's
@@ -303,10 +586,52 @@ jenkins_build_map() {
 # `LC_ALL=C` on the match: the CLI localises its messages, and a matcher that
 # only works in English would silently reclassify every miss as an outage for
 # anyone else.
+#
+# A MISSING CLI IS NOT A MISS, AND THE BARE `not found` ALTERNATIVE COULD NOT
+# TELL THEM APART. Measured 2026-09-06 with `gh` off `PATH`: the shell says
+# `bash: gh: command not found`, which matched — so `pr-merged` answered
+# `not-merged` where `plot-pr-merged.sh` answered `unaskable` about the same
+# branch. `not-merged` reads to `rules/landed.ts` as `none` (the host spoke and
+# said nothing merged), so `mayRemove` may permit a removal; `unaskable`
+# refuses. `plot-release-refs.sh` deletes remote refs on that answer and a
+# deleted ref is not re-creatable, so the two answers differ in the one
+# direction this estate has said it will not fail in.
+#
+# The bare alternative stays — it is what recognises a Bitbucket or Jira miss,
+# whose wording is neither `no pull requests found` nor `could not find`. What
+# it excludes is the shell's own phrasing for an absent binary, which is a
+# transport failure wearing a miss's words.
 is_lookup_miss() {
+  case "$1" in *'command not found'*) return 1 ;; esac
   LC_ALL=C grep -qiE 'no (pull request|pullrequest)s? (found|match)|could not find.*pull request|not found' <<<"$1"
 }
 
+# Did the host refuse this call for RATE, rather than answer it?
+#
+# THE GAP NO BUDGET READING CLOSES, and this is what closes it instead. A
+# secondary limit bounds requests AT ONCE rather than requests an hour, so it
+# fires while the pool is nearly full — measured 2026-09-01, `gh pr view`
+# refused while the same account's GraphQL header read 4854 of 5000. No reading
+# of any bucket predicts that, which is why the refusal itself is the evidence.
+#
+# Measured 2026-09-01. A polling burst tripped GitHub's secondary limit on
+# GraphQL while BOTH buckets read `5000/5000`, so `graphql_budget_spent` was
+# false, the cheap path was chosen, and every `gh pr` call returned
+# `API rate limit already exceeded`. REST answered the same questions normally
+# throughout. The estate's whole reap stalled on it — 18 worktrees read
+# `rule could not be asked` and every one was kept.
+#
+# THE CHEAP PATH STAYS THE DEFAULT. This does not prefer REST; the trade is
+# measured at one GraphQL call against ~186 REST calls for a 93-branch scan. It
+# only says that a call REFUSED for rate has not been answered, so the second
+# path is worth trying before reporting an outage.
+#
+# `LC_ALL=C` for the reason `is_lookup_miss` gives: the CLI localises, and an
+# English-only matcher would misread every other locale.
+is_rate_refusal() {
+  LC_ALL=C grep -qiE 'rate limit|secondary rate|abuse detection|403.*forbidden' <<<"$1"
+}
+
 # Emits the miss payload on a genuine miss and exits non-zero on anything else,
 # after putting the CLI's own words on stderr. Callers get: stdout parseable or
 # empty, exit code decisive.
@@ -345,19 +670,38 @@ host_miss_or_fail() {
 # there unused, and the same question can still be answered — degraded and more
 # expensive, but answered.
 #
-# BE HONEST ABOUT WHAT THIS BUYS. It is a second path when one bucket is
-# GENUINELY spent, which is a real state a long-running board reaches. It is NOT
-# immunity from throttling. The outage this repo actually had on 2026-08-27 was
-# GitHub's SECONDARY limit — concurrent-request throttling, eight workers
-# against a cap of seven — and during it both budgets read:
+# THIS GATE READ `gh api rate_limit` UNTIL 2026-09-02, AND IT COULD NOT SEE THE
+# CONDITION IT GATES ON. Measured 2026-09-01 in a quiet moment, same account,
+# seconds apart:
+#
+#   gh api rate_limit     graphql: 5000/5000, used 0
+#   a real call's header  X-Ratelimit-Remaining: 1236, Used: 3764
+#
+# Reproduced 2026-09-02: `rate_limit` reported 5000/5000 used 0 while the header
+# on the same account read `Remaining: 2732, Used: 2268`. So the `-eq 0` test
+# below has never been able to fire, and the fallback it guards has never been
+# reached by a budget reading.
+#
+# **A gate that cannot see the condition it gates on is worse than no gate,
+# because it reports safety.** Measured 2026-09-01: a polling burst tripped
+# GitHub's secondary limit on GraphQL while both buckets read `5000/5000`, this
+# gate was therefore false, the cheap path was chosen, and every `gh pr` call
+# returned `API rate limit already exceeded`. REST answered normally throughout.
+# The estate's whole reap stalled — 18 worktrees read `rule could not be asked`
+# and every one was kept.
 #
-#   graphql: 5000/5000  used=0  reset_in=3599s
-#   core:    5000/5000  used=0  reset_in=3599s
+# SO IT READS THE RECORD, AND THE RECORD IS WRITTEN FROM RESPONSE HEADERS. Every
+# `gh` call this script makes files its spend against the bucket it spent, and a
+# call that harvested `X-RateLimit-*` files the connector's own numbers with it.
+# Three properties follow, and each answers an objection to the old reading:
 #
-# Both full, nothing spent, every call refused. `rate_limit` does not report the
-# secondary limit and cannot, so this gate would have read 5000 available at the
-# exact moment nothing worked. Backing off on the 403 itself is a separate
-# change and is not this one.
+#   FREE       it reads a file. No host is asked, so the "the query is free"
+#              argument the old docblock made is no longer needed — nothing is
+#              spent at all, rather than one call against the bucket in question.
+#   CURRENT    the newest live line describes the last call that actually
+#              happened, not a separate endpoint's view of it.
+#   BY NAME    the line names its own bucket, so `graphql` is asked about
+#              `graphql` and a full `core` cannot answer for it.
 #
 # THE CHEAP PATH STAYS THE DEFAULT, and the reason is measured. For 93 branches:
 # ONE GraphQL call (`pr-list` with the check rollup) versus ~186 REST calls,
@@ -367,23 +711,131 @@ host_miss_or_fail() {
 # ACTUALLY spent.
 #
 # UNKNOWN IS NOT ZERO. #485 pinned that rule where it was informational; here is
-# where it bites. A host that cannot be asked reports `unknown`, and reading
-# that as "exhausted" would send every branch down the expensive path forever,
-# for as long as the budget query kept failing. So anything that is not a
-# number that is not greater than zero leaves the default alone.
+# where it bites. A record with no `graphql` line yet, a reading the connector
+# did not number, and an unreadable file all report `unknown` — and reading any
+# of them as "exhausted" would send every branch down the expensive path
+# forever. So only a `remaining` that IS a number and IS zero returns true.
+#
+# IT IS STILL BLIND TO THE SECONDARY LIMIT, and that is stated rather than
+# fixed here. A burst refusal arrives while the bucket has 4854 of 5000 left —
+# measured 2026-09-01 — so no reading of any bucket predicts it. What answers
+# that is the rate-refusal re-entry in `pr-state`, which reads the refusal
+# itself; `bug/a-spent-bucket-waits-for-its-reset` owns the reaction.
 graphql_budget_spent() {
-  local rate remaining
-  # The budget query is FREE — `gh api rate_limit` consumes neither bucket
-  # (measured 2026-08-27: three consecutive readings, all used=0) — so asking
-  # before each lookup costs nothing against either limit.
-  rate="$(gh api rate_limit 2>/dev/null)" || return 1
-  remaining="$(jq -r '.resources.graphql.remaining // "unknown"' <<<"$rate" 2>/dev/null)" || return 1
-  # `== 0` and not `<= 0`: only a number can be spent. `unknown`, an empty
-  # string and a malformed payload all fall through to false, which is the
-  # cheap path — the honest direction to be wrong in.
+  local rate remaining basis
+  # THE RECORD, NEVER THE HOST. `budget_rate` reads one file and asks nothing,
+  # so this costs no request against the bucket it is asking about — which the
+  # old reading did, on every lookup.
+  rate="$(budget_rate github "$(budget_account github)" graphql 2>/dev/null)" || return 1
+  remaining="$(jq -r '.remaining' <<<"$rate" 2>/dev/null)" || return 1
+  basis="$(jq -r '.basis' <<<"$rate" 2>/dev/null)" || return 1
+  # ONLY AN `actual` READING MAY CLOSE THIS GATE. A `predicted` number is the
+  # adapter's estimate of a ceiling and carries no spend against it; an
+  # `unknown` one is the absence of a reading. Neither is evidence that a
+  # bucket is empty, and treating either as one takes the expensive path on a
+  # guess.
+  [ "$basis" = actual ] || return 1
+  # `== 0` and not `<= 0`: only a number can be spent. `null`, an empty string
+  # and a malformed payload all fall through to false, which is the cheap path
+  # — the honest direction to be wrong in.
   [[ "$remaining" =~ ^[0-9]+$ ]] && [ "$remaining" -eq 0 ]
 }
 
+# THE ROUTER. One function decides REST versus GraphQL for the GitHub
+# connector, and it is the only place in this script that decides. Every GitHub
+# op asks it; no op re-derives the answer.
+#
+# `gh_route <op>` prints `graphql` or `rest`. The op is the argument because
+# the routing question is *"how should THIS question be asked?"*, and not every
+# question has two answers.
+#
+# ONE ROUTER PER CONNECTOR, NOT ONE FOR ALL OF THEM. REST-versus-GraphQL is a
+# GitHub distinction: Bitbucket has no such split, Jenkins has neither
+# transport, and GitLab will have its own. A router lifted above the adapters
+# would make every future connector implement a fork that exists for one
+# vendor. So this function is named `gh_`, sits beside the other `gh_` helpers,
+# and `bb`, `jen` and `jira` never reach it.
+#
+# NO CALLER LEARNS THE ROUTE. The answer is consumed inside this script and
+# never reaches stdout, and both paths normalise to one vocabulary — see
+# `rest_pr_to_state`, which exists so a REST answer is indistinguishable from a
+# GraphQL one.
+#
+# THE CHEAP PATH IS THE DEFAULT, and this function does not change that. For 93
+# branches: one GraphQL call against ~186 REST calls, because REST's list
+# endpoint carries no check rollup and no `mergeable_state`. So `graphql` is
+# what falls out when nothing says otherwise, and `rest` needs a reason.
+#
+# ONE `case`, NOT THREE PREDICATES. An earlier draft split "which transports
+# does this op have?" into two helper functions the router called. That is a
+# second site that decides, which is the exact thing this slice removes — a
+# reader would have had to hold three functions in mind to answer one question.
+# The transports an op has are stated here, once, beside the rule that reads
+# them.
+#
+# THE ARMS, AND WHY EACH IS WHERE IT IS:
+#
+#   pr-state          both transports. The only op with a REST fallback
+#                     written, so the only one where the budget can change the
+#                     answer.
+#   rate-limit|limit  REST-only BY NATURE rather than by omission. Both are
+#                     reached through `gh api`, which is REST's transport.
+#                     `limit` spends a GraphQL call to read its own headers —
+#                     the call it makes is GraphQL, the route to it is not.
+#   *                 GraphQL-only. Ten ops, and this is where "every op
+#                     consults the router" is honest rather than decorative:
+#                     their answer is a statement about what THIS SCRIPT has
+#                     implemented, not about what GitHub offers, which serves
+#                     nearly everything both ways. Saying so here puts the
+#                     knowledge where slice 7 can act on it, instead of leaving
+#                     it implicit in the absence of a branch at the call site.
+#                     Writing the missing REST paths is new capability and
+#                     belongs to no slice in this plan.
+#
+# `PLOT_HOST_FORCE_REST=1` IS NOT A DEBUG SWITCH. It is how the rate-refusal
+# re-entry reaches the second path without a second copy of the REST code:
+# `pr-state` re-enters itself with the variable set after GraphQL is refused
+# for rate. An operator may also set it, and that is supported, but the
+# re-entry is why it exists. It is consulted before the budget because it is
+# free and the budget read is not.
+#
+# THE BUDGET IS CONSULTED LAST, AND IT READS THE RECORD BY BUCKET NAME. Every
+# `gh` call files its spend against the pool it spent, and a call that harvested
+# `X-RateLimit-*` files the connector's own numbers with it — so `graphql` is
+# asked about `graphql`, and a `core` with 4990 left cannot answer for it.
+#
+# It read `gh api rate_limit` until 2026-09-02, and that reading could not see
+# the condition it gates on: the endpoint was measured 2026-09-01 reporting
+# `graphql: 5000/5000, used 0` while a real response header reported
+# `Remaining: 1236, Used: 3764`, and reproduced 2026-09-02 against a header's
+# 2732. So the `-eq 0` test never fired, and a gate that cannot see its
+# condition is worse than no gate because it reports safety.
+#
+# Last, because it is the only one of the three reasons that can be wrong. It
+# no longer costs a call to establish — the record is a file.
+gh_route() { # $1=op → graphql|rest
+  case "${1:-}" in
+    # REST-only: no GraphQL route exists to choose, so nothing is consulted.
+    rate-limit|limit)
+      printf 'rest\n'
+      ;;
+    # Both transports implemented — the one op where the reasons apply.
+    pr-state)
+      if [ "${PLOT_HOST_FORCE_REST:-0}" = "1" ] || graphql_budget_spent; then
+        printf 'rest\n'
+      else
+        printf 'graphql\n'
+      fi
+      ;;
+    # GraphQL-only. `PLOT_HOST_FORCE_REST` cannot move these: there is nowhere
+    # to move them TO, and answering `rest` would name a path that does not
+    # exist. An op that grows a REST fallback gets an arm above.
+    *)
+      printf 'graphql\n'
+      ;;
+  esac
+}
+
 # BOTH PATHS MUST PRODUCE ONE VOCABULARY, or the adapter's contract forks in two
 # and every caller has to learn which route answered.
 #
@@ -562,6 +1014,8 @@ bb_assert_issue_version() {
 BB_CAP_CHECKED=""
 BB_CAP_HAS_JSON=""
 BB_CAP_IDENTITY=""    # "craftamap/0.6.0" or "quatico/1.2.3" or "unknown/<ver>"
+BB_CAP_PROBE_RC=""    # the exit code `bb pr list --help --json` returned
+BB_CAP_PROBE_MATCH="" # the line that matched a rejection pattern, if one did
 
 # Identify which bb is on PATH. Returns a string like "quatico/1.9.0" or
 # "craftamap/0.6.0" or "unknown/<version>" or "unknown/unknown".
@@ -610,26 +1064,52 @@ bb_test_json_support() {
   local out rc
   out="$(bb pr list --help --json 2>&1)"; rc=$?
 
-  # craftamap 0.6.0 rejects --json with `Error: unknown flag: --json`
-  if grep -qiE 'unknown flag.*--json|invalid.*--json|--json.*not' <<<"$out"; then
-    return 1
-  fi
+  # WHAT WAS TESTED, kept for the refusal below. The diagnostic names the
+  # command, its exit code and the line that matched — three observations a
+  # reader can reproduce — rather than a provenance verdict `bb_identify`
+  # cannot determine. A message that guesses wrong costs more than one that
+  # says less.
+  BB_CAP_PROBE_RC="$rc"
+  BB_CAP_PROBE_MATCH=""
 
-  # If help succeeded (even partially), assume --json is supported
-  if [ "$rc" = 0 ]; then
-    return 0
+  # THE MEASUREMENT ANSWERS FIRST, AND THE TEXT ONLY WHEN IT IS ABSENT.
+  #
+  # `rc = 0` proves the flag PARSED: no CLI accepts an unknown flag and exits 0.
+  # That is a measurement. The grep below is a heuristic over prose, and asking
+  # the heuristic first is what issue #668 is.
+  #
+  # bb 1.9.0 documents that the flag is cheap — "a bare `--json`, costs nothing
+  # extra" — and `--json.*not` matched `--json, costs no`t`hing`, so a bb that
+  # WORKS was rejected for explaining the flag it supports. The bug therefore
+  # scaled with documentation quality: bb 1.0.0 lacks the sentence and passed.
+  [ "$rc" = 0 ] && return 0
+
+  # ANCHORED TO THE FLAG, WITH NO `.*` BRIDGE, so prose cannot reach them.
+  # These are what a CLI actually prints when it rejects a flag — Cobra, getopt
+  # and Go's `flag` respectively. craftamap 0.6.0 exits NON-ZERO on `--json`, so
+  # it never reached the early return above and its exact message still matches.
+  if grep -qiE 'unknown flag: --json|unknown option .?--json|flag provided but not defined: -?-json' <<<"$out"; then
+    BB_CAP_PROBE_MATCH="$(grep -iEm1 'unknown flag: --json|unknown option .?--json|flag provided but not defined: -?-json' <<<"$out")"
+    return 1
   fi
 
-  # Non-zero exit with no clear rejection — inspect further
-  # A "not a bitbucket repo" error is about the repo, not the flag
+  # A "not a bitbucket repo" error is about the repo, not the flag.
   if grep -qiE 'not a bitbucket repo|repository not found' <<<"$out"; then
-    # Could not test properly, but that is a repo issue, not a capability one.
-    # We will discover the real failure when the actual call is made.
     return 0
   fi
 
-  # Unknown failure — treat as unsupported to be safe
-  return 1
+  # AN UNRECOGNISED FAILURE ACCEPTS, and this is a behaviour change the plan
+  # argued for in round 1. Refusing on wording outside the three formats above
+  # is the same mistake as the bug this function is fixing, one arm along: a
+  # guess refusing a CLI that may work. A help call failing for some other
+  # reason is likelier an environment problem, and letting it through means the
+  # first real call fails with BB'S OWN ERROR — more accurate than any guess
+  # made here.
+  #
+  # The cost is stated rather than hidden: a genuinely incapable `bb` with
+  # unfamiliar wording now produces a downstream error instead of one clear
+  # message. That is the direction to fail, because the other direction is #668.
+  return 0
 }
 
 # Require that bb supports --json. Called once before the first bb PR call.
@@ -651,7 +1131,19 @@ bb_require_json() {
 
   if ! bb_test_json_support; then
     BB_CAP_HAS_JSON=0
-    die3 "bb on PATH ($BB_CAP_IDENTITY) does not support --json for PR commands — install Quatico's bb or ensure it is first on PATH"
+    # THE OBSERVATION FIRST, THE IDENTITY WHERE ONE IS KNOWN.
+    #
+    # The plan asked for the observation and for dropping the provenance CLAIM
+    # — `bb_identify` answers `unknown/<ver>` for Quatico's bb, so a message
+    # resting on it advised a working install to reinstall itself.
+    #
+    # But identity is not always unknown: craftamap reports a real version, and
+    # `host.test.mjs:1761` asserts the diagnostic names it. Both are right, and
+    # they do not conflict — an identity that IS determinable is a fact worth
+    # printing, and `bb_identify` already answers `unknown/<ver>` rather than
+    # inventing one where it is not. So this reports what was tested AND who
+    # answered, and it no longer tells anyone what to install.
+    die3 "bb ($BB_CAP_IDENTITY): bb pr list --help --json exited ${BB_CAP_PROBE_RC:-?}${BB_CAP_PROBE_MATCH:+, matched: $BB_CAP_PROBE_MATCH} — this bb does not support --json for PR commands"
   fi
 
   BB_CAP_HAS_JSON=1
@@ -751,6 +1243,25 @@ jira_curl() {
     -H 'Accept: application/json' \
     -w '\n%{http_code}' \
     "$base$path" "$@"
+  local rc=$?
+  # JIRA IS COUNTED HERE AND NOT BY A WRAPPER, because it is reached through
+  # `curl` rather than a CLI of its own — and shadowing `curl` would count every
+  # unrelated use of it. This is the one place plot speaks to a Jira, so it is
+  # the one place that records the spend, which is the same argument the `gh`
+  # wrapper makes one level up.
+  #
+  # The account is the Jira user, which is already in the environment and costs
+  # nothing to read — the one connector here whose account needs no lookup.
+  budget_record_jira
+  return $rc
+}
+
+# Records one Jira call. Jira meters, publishes no header this adapter reads,
+# and this slice does not add header parsing — so the reading is `unknown`,
+# which is never read as free.
+budget_record_jira() {
+  [ -z "${PLOT_BUDGET_OFF:-}" ] || return 0
+  budget_append jira "${JIRA_EMAIL:-unknown}" api 1 - - - unknown
 }
 
 # Split a jira_curl response into (body, status) and enforce the three outcomes.
@@ -852,10 +1363,466 @@ backend() {
   esac
 }
 
+
+# --- the connector counts what it spends -----------------------------------
+#
+# EVERY HOST CALL APPENDS ONE LINE, AND SO DOES EVERY REFUSAL. A record that
+# omits failures under-counts exactly when the count matters most: a refused
+# call spent quota — GitHub debits the request before it decides to refuse it —
+# and a budget blind to refusals reads a throttled account as an idle one.
+#
+# INSTRUMENTED BY SHADOWING, NOT BY EDITING 40 CALL SITES. `gh`, `bb` and `jen`
+# below are shell FUNCTIONS, and a function shadows a PATH executable for every
+# caller in this file. `command gh` reaches the real binary, so the wrapper is
+# the one place the counting happens and no call site changes.
+#
+# THE ALTERNATIVE WAS MEASURED AND REJECTED. This script makes ~40 host CLI
+# invocations across 14 backend branches; recording at each would be 40 edits
+# that must all stay right, and the arm that drifts is the one nobody's repo
+# exercises — the same argument `pr_list_call` makes for gathering six call
+# sites into one helper, and `plot-pr-merged.sh` makes for being sourced rather
+# than copied. A wrapper also counts a call site written NEXT year, which no
+# number of careful edits can.
+#
+# IT CHANGES NO BEHAVIOUR. The wrapper forwards argv untouched, passes stdin
+# through, preserves stdout, stderr and the exit code exactly, and appends
+# afterwards. A call that succeeds today succeeds identically with a line
+# written beside it.
+. "$here/plot-budget.sh"
+
+# WHO IS SPENDING — read from the CLI's own config, never from an API call.
+#
+# `gh api user` would answer authoritatively and cost one request against the
+# very bucket this is counting, on every invocation of this script. So the
+# account is read from `gh`'s config file, which `gh auth login` wrote and which
+# costs a file read. It is cached in an exported variable so a script that makes
+# several calls reads it once.
+#
+# AN UNKNOWN ACCOUNT IS RECORDED AS `unknown`, not skipped. Two checkouts whose
+# account cannot be read still share one real budget, and dropping their lines
+# would under-count the machine — the failure this plan exists to remove. They
+# group together under one honest name instead.
+budget_account() {
+  if [ -n "${PLOT_BUDGET_ACCOUNT:-}" ]; then printf '%s\n' "$PLOT_BUDGET_ACCOUNT"; return; fi
+  local who=''
+  case "$1" in
+    github)
+      # `gh`'s hosts.yml names the active user under the host it belongs to.
+      # `yq` is not a dependency here, and the file's shape is two levels of
+      # indentation, so the top-level `user:` key is read directly.
+      who="$(awk '/^[[:space:]]+user:/ {print $2; exit}' "${GH_CONFIG_DIR:-$HOME/.config/gh}/hosts.yml" 2>/dev/null)"
+      ;;
+    bitbucket)
+      # `bb_identify` already resolves who bb is, and it caches; but it runs a
+      # `bb` call, which is the thing being counted. The remote's owner is the
+      # free approximation and is the half of the key that groups correctly:
+      # two checkouts of one workspace share a budget.
+      who="$(git config --get remote.origin.url 2>/dev/null | sed -E 's#^.*[:/]([^/]+)/[^/]+(\.git)?$#\1#')"
+      ;;
+  esac
+  printf '%s\n' "${who:-unknown}"
+}
+
+# The bucket a call spent, in the connector's OWN word.
+#
+# TWO SOURCES, AND THE HEADER OUTRANKS THE ARGV. A response reports the bucket
+# it spent in `X-RateLimit-Resource` — `core`, `graphql`, and `code_search` for
+# a search, which no reading of the command line would ever name. So a call that
+# harvested a header records what the header said, and this function answers
+# only for the calls that could not.
+#
+# `gh` OFFERS NO HEADERS ON MOST OF ITS SURFACE. `gh pr list` and `gh issue
+# list` are `gh`'s own GraphQL wrappers: they print a rendered payload and there
+# is no flag that adds the response headers to it. `--verbose` writes the whole
+# exchange to STDOUT, which would corrupt every caller's parse. So the argv is
+# what remains, and it is enough for the split that matters: `gh api graphql` and
+# every `gh pr`/`gh issue` command spend `graphql`, while `gh api <path>`,
+# `gh run` and `gh repo` spend `core`.
+#
+# AN UNRECOGNISED VERB NAMES NO BUCKET, and that empty string is the honest
+# answer rather than a default. Guessing `core` for a command nobody has
+# classified would file its spend against a pool it never touched, and the
+# gate below reads that pool.
+#
+# NOT NORMALISED, EVER. A connector nobody has written an adapter for names a
+# third thing, and `BudgetKey` carries the bucket as an unvalidated string for
+# exactly that reason — see `packages/domain/src/entities/limit.ts`: *"A closed
+# set here is the edit that gets forgotten when GitLab arrives."*
+gh_bucket_of_argv() {
+  case "${1:-}" in
+    # `gh api graphql` is the ONE `gh api` form that is not REST, and it is
+    # named by its first positional rather than by a flag.
+    api) if [ "${2:-}" = graphql ]; then printf 'graphql\n'; else printf 'core\n'; fi ;;
+    # `gh`'s PR and issue commands are its GraphQL wrappers throughout.
+    pr|issue) printf 'graphql\n' ;;
+    # REST, all of them: `gh run list` reads the Actions API, `gh repo view`
+    # the repository one, and `gh auth` the user one.
+    run|repo|auth|release|workflow|search) printf 'core\n' ;;
+    *) printf '\n' ;;
+  esac
+}
+
+# The bucket a NON-GitHub connector spends.
+#
+# One bucket per connector, which is the truth for `bb`, `jen` and `jira`: each
+# meters one pool or none, and neither reports a resource name. GitHub is the
+# connector that meters several, and `gh_bucket_of_argv` above is what names
+# them.
+budget_bucket() {
+  case "$1" in
+    github) printf 'core\n' ;;
+    bitbucket) printf 'api\n' ;;
+    *) printf '\n' ;;
+  esac
+}
+
+# What the connector's basis is, WITHOUT spending a call to find out.
+#
+# `plot-host.sh limit` reads a real response's headers, and it costs one
+# request. Calling it from inside the wrapper would double every host call this
+# script makes — the failure mode in miniature. So the wrapper records the
+# basis it can state for free, and the numbers stay absent:
+#
+#   github     `unknown` — GitHub HAS an actual reading, and this wrapper does
+#              not hold it. Recording a `predicted` 5000 here would tag a
+#              constant as an estimate nobody made; recording `actual` would tag
+#              a guess as a measurement. `unknown` is the honest word, and
+#              `unknown` is NEVER read as free — `headroom()` returns null for
+#              it by construction.
+#   bitbucket  `predicted 1000` — the adapter's own number from experience, the
+#              same one `limit` reports, and it costs nothing to state.
+#
+# A CALL THAT HARVESTED ITS OWN HEADERS OVERRIDES THIS, and that is the whole
+# of what slice 7 adds: `gh_api_harvest` puts the response's own
+# `X-RateLimit-*` into `PLOT_BUDGET_HARVEST`, and `budget_record_call` reads
+# that in preference to this. The reading is then FREE — the call was going to
+# happen anyway — and CURRENT, because it describes the call that just
+# happened rather than a separate endpoint's view of it.
+budget_reading() { # $1=backend → "<limit>\t<remaining>\t<reset>\t<basis>"
+  # THE FIELDS ARE ARGUMENTS, NOT A FORMAT. Three of the four are the absent
+  # marker `-`, and `printf '-\t...'` reads that leading `-` as an option flag:
+  # bash answers `printf: -\: invalid option` and writes nothing. Measured
+  # 2026-09-02, that broke the GitHub arm — the common path — in 10 host tests.
+  case "$1" in
+    bitbucket) printf '%s\t%s\t%s\t%s\n' 1000 - - predicted ;;
+    *) printf '%s\t%s\t%s\t%s\n' - - - unknown ;;
+  esac
+}
+
+# The reading the LAST harvested response carried, as
+# "<bucket>\t<limit>\t<remaining>\t<reset>", or empty where nothing was
+# harvested.
+#
+# A SHELL VARIABLE RATHER THAN A RETURN, because the harvest happens inside a
+# command substitution — `out="$(gh_api_harvest …)"` — and a subshell's
+# variables do not survive it. So the harvester writes the reading to a file
+# whose path the parent chose, and the parent reads it back. A pipe would have
+# the same problem in the other direction.
+PLOT_BUDGET_HARVEST=""
+
+# Records one call against one connector, whatever it cost and however it ended.
+#
+# `PLOT_BUDGET_OFF=1` disables recording entirely. It is for the tests that must
+# prove the record changes NOTHING about a call's behaviour, and for an operator
+# whose home directory is read-only; it is not a performance switch.
+#
+# THE BUCKET IS THE THIRD ARGUMENT AND IT IS NOT OPTIONAL FOR GITHUB. One
+# connector meters several pools independently, and until this slice every
+# GitHub call was filed against one bucket named `api` — so a spent GraphQL pool
+# and a full REST one summed to a number describing neither. Measured
+# 2026-09-01 from the response headers: `core` 4990 of 5000, `graphql` 0 of
+# 5000.
+budget_record_call() { # $1=connector $2=backend-for-account $3=bucket
+  [ -z "${PLOT_BUDGET_OFF:-}" ] || return 0
+  local reading account bucket
+  account="$(budget_account "${2:-$1}")"
+  bucket="${3:-}"
+  [ -n "$bucket" ] || bucket="$(budget_bucket "$1")"
+  # A HARVESTED HEADER OUTRANKS EVERYTHING, including the argv's guess at the
+  # bucket: `X-RateLimit-Resource` names `code_search` for a search that no
+  # reading of the command line would have classified as anything but `core`.
+  if [ -n "${PLOT_BUDGET_HARVEST:-}" ]; then
+    IFS=$'\t' read -r _hbkt _blim _brem _brst <<<"$PLOT_BUDGET_HARVEST"
+    PLOT_BUDGET_HARVEST=""
+    [ -z "$_hbkt" ] || bucket="$_hbkt"
+    # `actual` is the one basis a caller is entitled to trust, and a harvested
+    # header is the only thing in this script that earns it: the connector said
+    # it, about the call that just happened.
+    budget_append "$1" "$account" "$bucket" 1 "$_blim" "$_brem" "$_brst" actual
+    return 0
+  fi
+  reading="$(budget_reading "$1")"
+  IFS=$'\t' read -r _blim _brem _brst _bbas <<<"$reading"
+  budget_append "$1" "$account" "$bucket" 1 "$_blim" "$_brem" "$_brst" "$_bbas"
+}
+
+# Reads `X-RateLimit-*` out of a header block, into the harvest variable.
+#
+#   plot_harvest_headers <file-holding-the-header-block>
+#
+# CASE-INSENSITIVE ON THE NAME. `gh` prints `X-Ratelimit-Limit` while GitHub
+# documents `X-RateLimit-Limit`, and a case-sensitive match reads a present
+# header as absent — which records `unknown` against a host that answered
+# perfectly.
+#
+# A MISSING HEADER LEAVES THE HARVEST EMPTY, so the caller records `unknown`
+# rather than a number. A proxy or an enterprise instance that strips them has
+# not reported a full budget and has not reported an empty one: `unknown` is
+# never `free`, and `headroom()` returns null for it by construction.
+plot_harvest_headers() {
+  local file="${1:-}" lim rem rst res
+  PLOT_BUDGET_HARVEST=""
+  [ -f "$file" ] || return 0
+  _hv() { LC_ALL=C grep -im1 "^$1:" "$file" | sed 's/^[^:]*:[[:space:]]*//' | tr -d '\r'; }
+  lim="$(_hv 'X-RateLimit-Limit')"
+  rem="$(_hv 'X-RateLimit-Remaining')"
+  rst="$(_hv 'X-RateLimit-Reset')"
+  res="$(_hv 'X-RateLimit-Resource')"
+  # A LIMIT THAT IS NOT A NUMBER IS NO READING AT ALL. The whole reading is
+  # dropped rather than half-kept: a bucket name beside an absent count would
+  # file a spend against a pool the record then reports as unknown, which is
+  # the shape a caller cannot act on.
+  [[ "$lim" =~ ^[0-9]+$ ]] || return 0
+  [[ "$rem" =~ ^[0-9]+$ ]] || rem='-'
+  [[ "$rst" =~ ^[0-9]+$ ]] || rst='-'
+  PLOT_BUDGET_HARVEST="$(printf '%s\t%s\t%s\t%s' "$res" "$lim" "$rem" "$rst")"
+}
+
+# `gh api` WITH ITS OWN HEADERS HARVESTED, and the body printed unchanged.
+#
+#   out="$(gh_api_harvest <args…>)"
+#
+# THE READING IS FREE BECAUSE THE CALL WAS GOING TO HAPPEN ANYWAY. `--include`
+# adds a header block to a request this script was already making, so no extra
+# request is spent — which is the objection that justified `gh api rate_limit`,
+# and it does not apply here. It is also CURRENT: it describes the call that
+# just happened rather than a separate endpoint's view of it. Measured
+# 2026-09-02 on this account, seconds apart: `gh api rate_limit` reported
+# graphql 5000/5000 used 0 while the same account's header read
+# `Remaining: 2732, Used: 2268`.
+#
+# STDOUT IS THE BODY AND NOTHING ELSE. The header block is split off here, so
+# every caller parses exactly what it parsed before. `--verbose` was the
+# alternative and it is unusable: `gh` writes the whole exchange to STDOUT,
+# which would corrupt the payload of every call that reads one.
+#
+# THE EXIT CODE AND STDERR ARE THE REAL CALL'S. A harvest that changed either
+# would make the reading cost correctness, which is the one price a bookkeeping
+# read may not charge.
+gh_api_harvest() {
+  local raw rc hdr_tmp err_tmp
+  hdr_tmp="$(mktemp "${TMPDIR:-/tmp}/plot-host-hdr.XXXXXX")" || {
+    # No temp file, no harvest — and the call still happens, recorded by the
+    # wrapper from its argv alone. Bookkeeping never fails its caller.
+    gh api "$@"
+    return $?
+  }
+  err_tmp="$(mktemp "${TMPDIR:-/tmp}/plot-host-herr.XXXXXX")" || {
+    rm -f "$hdr_tmp"
+    gh api "$@"
+    return $?
+  }
+  # `command gh`, NOT THE WRAPPER, and the reason is ordering. The wrapper
+  # records the call the moment it returns, which is before any header has been
+  # read — so a wrapped call here would file an `unknown` line and this
+  # function's reading would arrive too late to be the one recorded. Recording
+  # is therefore done below, once, with the header in hand.
+  # `--include` LAST, AFTER THE ENDPOINT. `gh` accepts it in either position,
+  # and the trailing one keeps the argv a reader — or a test's stub — sees
+  # identical up to the flag: `api repos/owner/repo/pulls/7 --include`, not
+  # `api --include repos/…`. The endpoint is what identifies the call.
+  raw="$(command gh api "$@" --include 2>"$err_tmp")"
+  rc=$?
+  # THE EXIT CODE AND STDERR ARE THE REAL CALL'S. A harvest that changed either
+  # would make the reading cost correctness, which is the one price a
+  # bookkeeping read may not charge — so the CLI's own words are replayed on
+  # this function's stderr exactly as they arrived.
+  cat "$err_tmp" >&2
+  rm -f "$err_tmp"
+  if [ $rc -ne 0 ]; then
+    rm -f "$hdr_tmp"
+    # A FAILED CALL IS STILL A SPENT CALL on every refusal GitHub meters, so it
+    # is recorded like any other — from the argv, with no numbers.
+    budget_record_call github github "$(gh_bucket_of_argv api "$@")"
+    return $rc
+  fi
+  # THE STATUS LINE IS WHAT PROVES A HEADER BLOCK IS THERE, and the check is not
+  # defensive padding. `sed '1,/^$/d'` on a body with NO header block deletes
+  # everything up to the first blank line IN THE BODY — pretty-printed JSON has
+  # none, so the whole payload would go. A `gh` too old for `--include`, or one
+  # that ignores it, produces exactly that input.
+  if [[ "$raw" != HTTP/* ]]; then
+    budget_record_call github github "$(gh_bucket_of_argv api "$@")"
+    printf '%s\n' "$raw"
+    return 0
+  fi
+  # `--include` prints the status line, the headers, a BLANK line, then the
+  # body. The blank line is the split, and it carries a CR — the headers are
+  # CRLF-terminated while the body is not — so the match tolerates one.
+  printf '%s\n' "$raw" | LC_ALL=C sed -n '1,/^[[:space:]]*$/p' >"$hdr_tmp"
+  plot_harvest_headers "$hdr_tmp"
+  rm -f "$hdr_tmp"
+  # THE ARGV NAMES THE BUCKET WHERE THE HEADER DID NOT. A response that carried
+  # no `X-RateLimit-Resource` still spent something, and `gh api <path>` is
+  # `core` by construction — so the call is recorded either way, and only the
+  # numbers are absent.
+  budget_record_call github github "$(gh_bucket_of_argv api "$@")"
+  # The body is everything after the first blank line. `sed` rather than a
+  # bash parameter expansion: the body may be megabytes of JSON, and the
+  # expansion would hold two copies of it.
+  printf '%s\n' "$raw" | LC_ALL=C sed '1,/^[[:space:]]*$/d'
+  return 0
+}
+
+# THE WRAPPERS. Each forwards argv untouched and returns the real CLI's exit
+# code unchanged; the append happens after, and `budget_append` never fails its
+# caller. `command` is what reaches past the function to the binary.
+#
+# THE BUCKET IS READ FROM THE ARGV THIS WRAPPER ALREADY HOLDS. `gh api graphql`
+# and `gh pr view` spend `graphql`; `gh api repos/…` and `gh run list` spend
+# `core`. A harvested header overrides it where one was taken — see
+# `budget_record_call`.
+# ── The concurrency bound ────────────────────────────────────────────────────
+#
+# HOW MANY CALLS THIS ACCOUNT MAY HAVE OPEN AT ONCE. The wrappers below claim a
+# slot before the CLI runs and give it back after, so eight workers running this
+# script at once compete for one account's cap rather than all calling together
+# — which is exactly what 2026-08-27 measured: eight workers, a 403 naming abuse
+# detection, and both buckets reading `5000/5000 used=0`.
+#
+# **DISCOVERED, NOT CONFIGURED.** `seven` has no independent source — the two
+# comments in this file that cite it cite the one incident, where eight failed
+# and seven is the inference — so no number is compiled in here. The bound is
+# derived from the ceiling the record already holds, by the arithmetic
+# `boundFromLimit` states: a limit is requests per HOUR and a bound is requests
+# at one MOMENT, so an account allowed `limit` an hour can sustain
+# `limit / (3600 / 4)` of them simultaneously at four seconds a call.
+#
+# **AND A CONNECTOR THAT REPORTS NOTHING IS UNBOUNDED**, which is what every
+# caller was before this slice. `unknown` is not a number, and a bound invented
+# here would be the compiled-in seven under another name.
+PLOT_SLOT_SECONDS=4
+
+# The bound for one connector and account, from the record's own reading.
+# Prints nothing and exits 1 where nothing licenses a bound.
+host_concurrency_bound() { # $1=connector $2=account
+  local rate limit basis
+  rate="$(budget_rate "$1" "$2" '' 2>/dev/null)" || return 1
+  basis="$(printf '%s' "$rate" | LC_ALL=C sed -n 's/.*"basis":"\([a-z]*\)".*/\1/p')"
+  [ "$basis" = actual ] || [ "$basis" = predicted ] || return 1
+  limit="$(printf '%s' "$rate" | LC_ALL=C sed -n 's/.*"limit":\([0-9]*\).*/\1/p')"
+  case "$limit" in ''|*[!0-9]*) return 1 ;; esac
+  [ "$limit" -gt 0 ] || return 1
+  local bound=$(( limit * PLOT_SLOT_SECONDS / 3600 ))
+  # NEVER ZERO. A bound of zero is a connector that can never be called again,
+  # which no reading licenses.
+  [ "$bound" -ge 1 ] || bound=1
+  printf '%s\n' "$bound"
+}
+
+# How long a caller keeps asking for a slot before it proceeds anyway, and how
+# often it asks. Thirty seconds is the queue eight deep draining at four seconds
+# a call; a caller still waiting after it PROCEEDS rather than refusing, because
+# a script that waited forever would hang a worker where the plan asks only that
+# the cadence degrade. The cost of one extra simultaneous call is a secondary
+# refusal that lowers the bound — evidence, through the mechanism this slice is
+# built on.
+PLOT_SLOT_WAIT_MAX_S=30
+PLOT_SLOT_POLL_S=1
+
+# The slot this process holds, so the wrappers can give it back. Empty where
+# none was taken — an unbounded connector, or a wait that ran out.
+PLOT_SLOT_INDEX=''
+PLOT_SLOT_ACCOUNT=''
+
+# Claims a slot for the call about to be made, waiting where the account is
+# busy. Never refuses: at worst it proceeds unbounded, which is what every
+# caller did before this slice.
+host_slot_take() { # $1=connector $2=backend-for-account
+  PLOT_SLOT_INDEX=''; PLOT_SLOT_ACCOUNT=''
+  [ -z "${PLOT_BUDGET_OFF:-}" ] || return 0
+  local account bound waited=0 got
+  account="$(budget_account "${2:-$1}")" || return 0
+  bound="$(host_concurrency_bound "$1" "$account")" || return 0
+  local rc
+  while :; do
+    # CAPTURED IMMEDIATELY, because `$?` after an `if` reports the `if`. The
+    # three exits mean three different things and collapsing any two of them is
+    # the defect this whole plan is about.
+    got="$(budget_slot_acquire "$account" "$bound")"; rc=$?
+    if [ "$rc" -eq 0 ]; then
+      PLOT_SLOT_INDEX="$got"; PLOT_SLOT_ACCOUNT="$account"; return 0
+    fi
+    # Exit 2 is *the claims could not be managed*, which is not the account
+    # being busy — and a script that stopped calling because a directory could
+    # not be created would go dark on a disk fault. It proceeds.
+    [ "$rc" -eq 1 ] || return 0
+    [ "$waited" -lt "$PLOT_SLOT_WAIT_MAX_S" ] || return 0
+    sleep "$PLOT_SLOT_POLL_S"
+    waited=$(( waited + PLOT_SLOT_POLL_S ))
+  done
+}
+
+# Gives the slot back. Called on every path out of a wrapper, taken or not.
+host_slot_give() {
+  [ -n "$PLOT_SLOT_INDEX" ] || return 0
+  budget_slot_release "$PLOT_SLOT_ACCOUNT" "$PLOT_SLOT_INDEX"
+  PLOT_SLOT_INDEX=''; PLOT_SLOT_ACCOUNT=''
+}
+
+gh() {
+  host_slot_take github github
+  command gh "$@"
+  local rc=$?
+  host_slot_give
+  budget_record_call github github "$(gh_bucket_of_argv "$@")"
+  return $rc
+}
+
+bb() {
+  host_slot_take bitbucket bitbucket
+  command bb "$@"
+  local rc=$?
+  host_slot_give
+  budget_record_call bitbucket bitbucket
+  return $rc
+}
+
+jen() {
+  host_slot_take jenkins ''
+  command jen "$@"
+  local rc=$?
+  host_slot_give
+  # Jenkins is the CI axis, a connector of its own — this repo is GitHub +
+  # Actions while `ekzweb` is Bitbucket + Jenkins, so a `jen` call spends
+  # against a server the git host knows nothing about.
+  budget_record_call jenkins ''
+  return $rc
+}
+
 op="${1:-}"; [ -n "$op" ] || die "usage: plot-host.sh <op> [args...] (see header)"
 shift
 be="$(backend)" || exit 1
 
+# EVERY GITHUB OP CONSULTS THE ROUTER, ONCE, HERE. `gh_route` is asked before
+# the op runs and its answer is read from `$route` by whichever arm needs it —
+# so an op cannot spend a GitHub call without the route for that call having
+# been decided, and there is no second place where an op could decide it.
+#
+# ASKED ONCE PER RUN, NOT ONCE PER CALL. `pr-state`'s arm reads the budget, and
+# that read is free (`gh api rate_limit` consumes neither bucket, measured
+# 2026-08-27) but not instant. One process answers one op, so one reading is
+# the whole of what that process needs.
+#
+# ONLY WHEN THE BACKEND IS GITHUB. The route is a GitHub distinction and this
+# is the connector boundary: a Bitbucket or Jenkins run never reaches
+# `gh_route`, never reads a budget, and `$route` stays empty for it. That
+# emptiness is the honest value — there is no route where there is no fork.
+route=""
+if [ "$be" = "github" ]; then
+  route="$(gh_route "$op")"
+fi
+
 case "$op" in
   backend)
     echo "$be"
@@ -882,11 +1849,11 @@ case "$op" in
       esac
     done
     if [ "$be" = "github" ]; then
-      # THE ROUTE IS CHOSEN ONCE, HERE, and the cheap path is the default. See
-      # `graphql_budget_spent` above for why REST is the exception rather than
-      # the rule (~186 calls versus one for a 93-branch scan) and for what this
-      # fallback honestly does and does not buy.
-      if graphql_budget_spent; then
+      # THE ROUTE IS NOT CHOSEN HERE. `gh_route` chooses it, for every op,
+      # and this site only reads the answer — see that function for why the
+      # cheap path is the default (~186 REST calls against one GraphQL call
+      # for a 93-branch scan) and for what the fallback honestly buys.
+      if [ "$route" = "rest" ]; then
         # THE GRAPHQL PATH IS NOT ATTEMPTED FIRST once its budget is known to be
         # gone. Trying it anyway would spend a call that is already refused, to
         # learn what was just read for free.
@@ -896,7 +1863,7 @@ case "$op" in
         # place that knows how to read either.
         rest_repo="$(gh_rest_repo)" || exit $?
         if [[ "$ref" =~ ^[0-9]+$ ]]; then
-          if out="$(gh api "repos/$rest_repo/pulls/$ref" 2>/tmp/plot-host-err.$$)"; then
+          if out="$(gh_api_harvest "repos/$rest_repo/pulls/$ref" 2>/tmp/plot-host-err.$$)"; then
             rm -f "/tmp/plot-host-err.$$"
             rest_pr_to_state <<<"$out"
           else
@@ -913,7 +1880,7 @@ case "$op" in
           # `state=all`, because the default is `open` and a merged PR would
           # otherwise read as NONE — wrong in the reassuring direction.
           rest_owner="${rest_repo%%/*}"
-          if out="$(gh api "repos/$rest_repo/pulls?head=$rest_owner:$ref&state=all&per_page=1" 2>/tmp/plot-host-err.$$)"; then
+          if out="$(gh_api_harvest "repos/$rest_repo/pulls?head=$rest_owner:$ref&state=all&per_page=1" 2>/tmp/plot-host-err.$$)"; then
             rm -f "/tmp/plot-host-err.$$"
             if [ "$(jq -r 'length' <<<"$out" 2>/dev/null)" = "0" ]; then
               echo '{"number":0,"state":"NONE","draft":false,"url":"","mergeCommit":""}'
@@ -934,6 +1901,14 @@ case "$op" in
         jq -c '{number:.number,state:.state,draft:.isDraft,url:.url,mergeCommit:(.mergeCommit.oid // "")}' <<<"$out"
       else
         err="$(cat "/tmp/plot-host-err.$$" 2>/dev/null)"; rm -f "/tmp/plot-host-err.$$"
+        # REFUSED FOR RATE IS NOT ANSWERED. The budget gate above could not see
+        # this coming — `rate_limit` does not report the secondary limit — so the
+        # cheap path was chosen and then declined. The second path is the one
+        # thing left to try before calling the host unreachable, and re-entering
+        # the op is how it is reached without a second copy of the REST code.
+        if is_rate_refusal "$err"; then
+          PLOT_HOST_FORCE_REST=1 "$0" pr-state "$ref" ${repo_args[@]+"${repo_args[@]}"} && exit 0
+        fi
         host_miss_or_fail "$err" \
           '{"number":0,"state":"NONE","draft":false,"url":"","mergeCommit":""}' || exit $?
       fi
@@ -995,6 +1970,77 @@ case "$op" in
     fi
     ;;
 
+  # HAS ANY PR FOR THIS BRANCH MERGED?
+  #
+  # The one operation `plot-reap.sh` and `plot-release-refs.sh` reached past
+  # this adapter for. `pr-state` returns `mergeCommit` and not `mergedAt`, and
+  # `mergeCommit` is empty for a branch whose merge this port never saw — so
+  # the gate that decides whether work has landed had to source its own
+  # implementation rather than ask here.
+  #
+  # THREE ANSWERS, ON EXIT 0. `unknown` is a payload, not a failure: a host
+  # that cannot be asked must not answer `not-merged`, because every caller is
+  # deciding whether to remove something. Exit 3 is still reserved for the call
+  # itself failing in a way this adapter does not recognise as a miss.
+  pr-merged)
+    ref="${1:?pr-merged needs a branch}"; shift || true
+    repo_args=()
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --repo) repo_args=(-R "${2:?}"); shift 2 ;;
+        *) die "pr-merged: unknown arg $1" ;;
+      esac
+    done
+    if [ "$be" = "github" ]; then
+      # --state all, because a merged PR reports CLOSED and the default `open`
+      # would hide every one of them. --limit 100 rather than 1: the newest PR
+      # is not the merge, exactly as the state is not the merge.
+      if out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr list --head "$ref" --state all --limit 100 --json mergedAt 2>/tmp/plot-host-err.$$)"; then
+        rm -f "/tmp/plot-host-err.$$"
+        if jq -e 'any(.[]; .mergedAt != null)' >/dev/null 2>&1 <<<"$out"; then
+          echo "merged"
+        else
+          echo "not-merged"
+        fi
+      else
+        err="$(cat "/tmp/plot-host-err.$$" 2>/dev/null)"; rm -f "/tmp/plot-host-err.$$"
+        # A LOOKUP MISS IS AN ANSWER — the branch has no PR, so nothing merged.
+        # Anything else is the host failing to be asked, and that is `unknown`
+        # rather than exit 3: the caller asked a question with a third value
+        # for exactly this case, and the answer fails safe toward keeping.
+        if [ -z "$err" ] || is_lookup_miss "$err"; then
+          echo "not-merged"
+        else
+          echo "plot-host: $err" >&2
+          echo "unknown"
+        fi
+      fi
+    else
+      bb_require_json
+      # Bitbucket has no `--head` filter, so the branch is matched locally.
+      # MERGED is bb's own state word here rather than a timestamp: the API
+      # exposes no `mergedAt`, so this is the closest fact the backend holds,
+      # and it is a positive statement about the merge rather than an inference
+      # from CLOSED — `DECLINED` is bb's closed-unmerged word and is distinct.
+      if out="$(bb ${repo_args[@]+"${repo_args[@]}"} pr list --state merged --json 2>/tmp/plot-host-err.$$)"; then
+        rm -f "/tmp/plot-host-err.$$"
+        if jq -e --arg b "$ref" 'any(.[]; .source.branch.name==$b)' >/dev/null 2>&1 <<<"$out"; then
+          echo "merged"
+        else
+          echo "not-merged"
+        fi
+      else
+        err="$(cat "/tmp/plot-host-err.$$" 2>/dev/null)"; rm -f "/tmp/plot-host-err.$$"
+        if [ -z "$err" ] || is_lookup_miss "$err"; then
+          echo "not-merged"
+        else
+          echo "plot-host: $err" >&2
+          echo "unknown"
+        fi
+      fi
+    fi
+    ;;
+
   pr-create)
     title=""; body=""; base=""; head=""; draft=0
     while [ $# -gt 0 ]; do
@@ -1067,6 +2113,13 @@ case "$op" in
   pr-list)
     state="open"
     rich=0
+    # PIN THE LIST TO ONE REPOSITORY, the same `--repo` `pr-state` and
+    # `pr-merged` already take. A checkout may carry several remotes on several
+    # hosts, and an unpinned `gh pr list` resolves whichever of them it prefers
+    # — so a caller comparing `origin/*` refs would join its refs against
+    # another repository's PRs and report every branch as having none. The
+    # caller knows which remote its refs came from; this op cannot guess it.
+    repo_args=()
     # `gh pr list` and `bb pr list` both cap at 30 by default. That is invisible
     # with --state open (few repos have 30 open PRs) and bites immediately with
     # --state all, where the newest 30 crowd out every older merged PR. A caller
@@ -1078,6 +2131,7 @@ case "$op" in
         --state) state="${2:?}"; shift 2 ;;
         --limit) limit="${2:?}"; shift 2 ;;
         --rich) rich=1; shift ;;
+        --repo) repo_args=(-R "${2:?}"); shift 2 ;;
         *) die "pr-list: unknown arg $1" ;;
       esac
     done
@@ -1196,8 +2250,8 @@ case "$op" in
           #   $jstatus != "ok"  → Jenkins could not answer; every row `unknown`.
           #   $jentry == null   → the branch has no Jenkins job; `none`.
           #   otherwise         → the joined colour's `checks`, job named on fail.
-          _gh_raw="$(gh pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
-            --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url)"
+          _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
+            --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url)" || exit $?
           pr_list_report_truncation github "$limit" "$state" \
             "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
           printf '%s' "$_gh_raw" \
@@ -1225,8 +2279,8 @@ case "$op" in
               }'
         else
           # GitHub without Jenkins (or Jenkins not configured): use GitHub rollup
-          _gh_raw="$(gh pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
-            --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url)"
+          _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
+            --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url)" || exit $?
           pr_list_report_truncation github "$limit" "$state" \
             "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
           printf '%s' "$_gh_raw" \
@@ -1256,8 +2310,8 @@ case "$op" in
               }'
         fi
       else
-        _gh_raw="$(gh pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
-          --json number,title,state,headRefName)"
+        _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
+          --json number,title,state,headRefName)" || exit $?
         pr_list_report_truncation github "$limit" "$state" \
           "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
         printf '%s' "$_gh_raw" \
@@ -1296,7 +2350,7 @@ case "$op" in
           # the GitHub arm uses, which is why it lives above the backend branch.
           # `bb`'s standing `unknown` becomes a real value where Jenkins answers.
           for _s in $bb_states; do
-            _bb_raw="$(bb pr list --state "$_s" --json)"
+            _bb_raw="$(pr_list_call bb ${repo_args[@]+"${repo_args[@]}"} pr list --state "$_s" --json)" || exit $?
             pr_list_report_truncation bitbucket "$limit" "$_s" \
               "$(jq 'length' <<<"$_bb_raw" 2>/dev/null || echo 0)"
             printf '%s' "$_bb_raw" \
@@ -1325,7 +2379,7 @@ case "$op" in
         else
           # Bitbucket without Jenkins: checks remain unknown
           for _s in $bb_states; do
-            _bb_raw="$(bb pr list --state "$_s" --json)"
+            _bb_raw="$(pr_list_call bb ${repo_args[@]+"${repo_args[@]}"} pr list --state "$_s" --json)" || exit $?
             pr_list_report_truncation bitbucket "$limit" "$_s" \
               "$(jq 'length' <<<"$_bb_raw" 2>/dev/null || echo 0)"
             printf '%s' "$_bb_raw" \
@@ -1334,7 +2388,7 @@ case "$op" in
         fi
       else
         for _s in $bb_states; do
-          _bb_raw="$(bb pr list --state "$_s" --json)"
+          _bb_raw="$(pr_list_call bb ${repo_args[@]+"${repo_args[@]}"} pr list --state "$_s" --json)" || exit $?
           pr_list_report_truncation bitbucket "$limit" "$_s" \
             "$(jq 'length' <<<"$_bb_raw" 2>/dev/null || echo 0)"
           printf '%s' "$_bb_raw" \
@@ -1383,6 +2437,84 @@ case "$op" in
     fi
     ;;
 
+  run-for-sha)
+    # The newest run for ONE sha — the BuildMonitor's only host question.
+    #
+    # WHY THIS IS NOT `runs`. `runs` is branch-scoped and reports no sha at all,
+    # so a caller cannot tell which commit an answer is about. `gh run list
+    # --branch X` returns runs for every sha the branch ever had, and the newest
+    # run is not necessarily for the newest commit — a branch pushed twice in
+    # quick succession has the first sha's run finishing after the second sha's
+    # started. Reading a conclusion off that run answers about the past.
+    #
+    # WHY THAT MATTERS MORE THAN IT SOUNDS. A green result for superseded code
+    # is worse than no result: it invites a merge of the wrong thing. Measured
+    # 2026-08-30, in the session that wrote the plan: two merge waiters reported
+    # on superseded runs and had to be stopped and re-armed.
+    #
+    # FACTS, NEVER A VERDICT (Principle 3). It reports `status` and `conclusion`
+    # as the host gives them and compares nothing. Whether `action_required`
+    # means "blocked" or `null` means "still going" is the monitor's rule, not
+    # this collector's — and keeping the two words separate is what lets the
+    # monitor tell a build awaiting a human click from one merely running. A
+    # collector that folded them into one word would make that distinction
+    # unrecoverable downstream.
+    #
+    # ONE OBJECT OR NOTHING. Empty output means the host has no run for this sha
+    # — which is a real, common answer (the run has not been created yet) and
+    # deliberately NOT an error: a monitor polling a fresh push sees it on every
+    # pass until CI wakes up.
+    #
+    # Bitbucket reports nothing rather than something invented, exactly as
+    # `runs` does: `bb` has no run listing, and silence here reads as
+    # unavailable, never as "this sha has no build".
+    branch="${1:?run-for-sha needs a branch}"; shift
+    sha="${1:?run-for-sha needs a sha}"; shift
+    # Enough runs to find the sha among its neighbours. A branch accumulates
+    # runs per push and per workflow, so the sha being asked about can sit
+    # several entries down even when it is the current head.
+    limit=20
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --limit) limit="${2:?}"; shift 2 ;;
+        *) die "run-for-sha: unknown arg $1" ;;
+      esac
+    done
+    if [ "$be" = "github" ]; then
+      # `headSha` is the field that makes this answerable at all; `runs` omits
+      # it, which is why that op cannot be reused here.
+      #
+      # NEWEST FIRST, then the FIRST match is taken: `gh run list` returns runs
+      # newest-first, and a sha can carry several (a rerun, or several
+      # workflows). The newest is the live answer; older ones for the same sha
+      # are superseded by the same argument that superseded runs for older shas.
+      # THE SHA ASKED ABOUT IF THERE IS ONE, ELSE THE NEWEST RUN ON THE BRANCH —
+      # and `sha` in the output says WHICH, because a caller that could not tell
+      # the two apart would be back to the branch-scoped guessing this op exists
+      # to end.
+      #
+      # WHY IT FALLS BACK AT ALL, rather than reporting nothing. Filtering to
+      # the asked-for sha and stopping makes the most important case invisible:
+      # a run IN FLIGHT for a commit the branch has already moved past reports
+      # identically to no run at all, so a caller cannot distinguish *CI has not
+      # started yet* from *CI is busy answering about the past*. The second is
+      # the state that had two merge waiters reporting on superseded runs on
+      # 2026-08-30, and it is exactly what a caller needs to see.
+      #
+      # IT STILL DECIDES NOTHING (Principle 3). It reports the run it found and
+      # the sha that run is for; whether that sha being different from the one
+      # asked about means "superseded" is the caller's rule. This collects.
+      gh run list --branch "$branch" --limit "$limit" \
+        --json headSha,conclusion,status,startedAt,url 2>/dev/null \
+        | jq -c --arg sha "$sha" \
+            '(map(select(.headSha == $sha)) | .[0]) // .[0]
+             | select(. != null)
+             | {sha:.headSha, status:.status,
+                conclusion:(if (.conclusion // "") == "" then null else .conclusion end),
+                url:.url, startedAt:.startedAt}' 2>/dev/null || true
+    fi
+    ;;
+
   issue-list)
     # Open tracker issues — the board's inbox, and READ-ONLY in both
     # directions. Nothing here writes a label, an assignee or a close: the
@@ -1612,6 +2744,55 @@ case "$op" in
     fi
     ;;
 
+  issue-status)
+    # THE ONE WRITE TO A TRACKER, and the amendment this op records: Plot writes
+    # a STATUS to the tracker it was told about, and writes nothing else. No
+    # ticket is created, none is closed, no comment, label or assignee is
+    # touched. A plan referencing an issue stays Plot's record; the status is
+    # the one fact the tracker owns a copy of, because it is the one a person
+    # reads in the tracker rather than in Plot.
+    #
+    # JIRA ONLY, and deliberately so rather than by omission. This vendor's
+    # projects surface has a script of its own (`plot-update-board.sh`) reached
+    # by its own connector, and the two write through different APIs under
+    # different credentials — which is why the tracker port has two connectors
+    # rather than one arm with a branch. A repo whose `Tracker` is not jira gets
+    # exit 4 here: this adapter cannot be asked, which is not a failure and not
+    # a silent success.
+    #
+    # IDEMPOTENT BY NATURE. The same status written twice is the same status,
+    # and Jira answers a transition to the state an issue already holds by
+    # naming no such transition — which this reports as `no-target` rather than
+    # as a failure.
+    key="${1:?issue-status needs an issue key}"; shift
+    want="${1:?issue-status needs a status}"; shift
+    [ "$(tracker_scheme)" = "jira" ] || exit 4
+    jira_require_config
+    # THE TRANSITION IS LOOKED UP, NEVER GUESSED. Jira transitions are per
+    # workflow and per issue: the id for "In Progress" differs between projects
+    # and the transition may not be available from the issue's current state at
+    # all. A hardcoded id writes a status to the wrong column silently.
+    raw="$(jira_curl "/rest/api/2/issue/$key/transitions")"; curl_rc=$?
+    body_json="$(jira_check "$raw" "$curl_rc")" || exit $?
+    tid="$(printf '%s' "$body_json" | jq -r --arg want "$want" \
+      '[.transitions[]? | select((.name // "" | ascii_downcase) == ($want | ascii_downcase)
+                                 or ((.to.name // "" | ascii_downcase) == ($want | ascii_downcase)))]
+       | .[0].id // ""')"
+    if [ -z "$tid" ]; then
+      # NO SUCH TRANSITION IS AN ANSWER, not a failure. The tracker was reached
+      # and holds nowhere to put this status — either the workflow has no such
+      # state or the issue is already in it. Reporting it as a failure would
+      # make a repeated write look like an outage.
+      printf '%s\n' 'no-target'
+      exit 0
+    fi
+    raw="$(jira_curl "/rest/api/2/issue/$key/transitions" \
+             -X POST -H 'Content-Type: application/json' \
+             --data "$(jq -cn --arg id "$tid" '{transition:{id:$id}}')")"; curl_rc=$?
+    jira_check "$raw" "$curl_rc" >/dev/null || exit $?
+    printf '%s\n' 'written'
+    ;;
+
   pr-body)
     num="${1:?pr-body needs a PR number}"; shift
     body=""
@@ -1680,7 +2861,203 @@ case "$op" in
     fi
     ;;
 
+  limit)
+    # WHAT IS THIS CONNECTOR'S LIMIT, AND HOW WELL DOES IT KNOW IT?
+    #
+    # One JSON line per bucket the connector meters:
+    #   {"connector":"github","bucket":"graphql","limit":5000,
+    #    "remaining":1236,"reset":1788269670,"basis":"actual"}
+    #
+    # `basis` is `actual` where the connector reported the numbers, `predicted`
+    # where this adapter supplied them from experience, and `unknown` where it
+    # reports nothing and there is nothing to predict. `limit`, `remaining` and
+    # `reset` are numbers or null; `reset` is epoch SECONDS.
+    #
+    # NOT `gh api rate_limit`, AND THAT IS THE WHOLE POINT OF THIS OP. Measured
+    # 2026-09-01 in a quiet moment, same account, seconds apart:
+    #
+    #   gh api rate_limit    graphql: 5000/5000, used 0
+    #   a real call's header X-Ratelimit-Remaining: 1236, Used: 3764
+    #
+    # 3764 calls spent, reported as zero. The endpoint is wrong when nothing is
+    # wrong, so `graphql_budget_spent()` above — which reads it and tests
+    # `-eq 0` — has never been able to fire. The authority is the header on a
+    # response that actually came back.
+    #
+    # THIS CALL SPENDS ONE REQUEST, AND SAYS SO. It asks the cheapest real
+    # question there is — `{viewer{login}}` — and reports what its response
+    # carried. One request against the bucket it reports is an honest cost; a
+    # free reading of the wrong number is not.
+    #
+    # THE OTHER READINGS ARE FREE, and this op is the one that is not. Every
+    # `gh api` call the adapter makes harvests its own headers through
+    # `gh_api_harvest`, on a request that was going to happen anyway, and files
+    # the reading in the budget record. So a caller that merely wants to know
+    # whether a pool is spent reads the record and spends nothing; this op is
+    # for a caller that wants a reading NOW, on a connector that may not have
+    # been called yet.
+    #
+    # `gh pr list` CANNOT BE HARVESTED. It is `gh`'s own GraphQL wrapper: no
+    # flag adds the response headers, and `--verbose` writes the whole exchange
+    # to stdout, which would corrupt every caller's parse. So a GraphQL call
+    # names its bucket from the argv and records no numbers — `unknown`, which
+    # is never read as free.
+    #
+    # ONE BUCKET, NOT TWO. A response reports the bucket IT spent, in
+    # `X-RateLimit-Resource`. Reporting `core` from a GraphQL response would be
+    # inventing a reading nobody took — the mistake `rate_limit` makes by
+    # answering for both at once.
+    if [ "$be" = "github" ]; then
+      _hdr_tmp="/tmp/plot-host-limit.$$"
+      # `command gh`, NOT THE WRAPPER, and for the ordering reason
+      # `gh_api_harvest` gives: the wrapper records the moment the call returns,
+      # before any header has been read, so a wrapped call here would file an
+      # `unknown` line AND this arm would file the real one — two lines for one
+      # request, which over-counts the very spend the record exists to measure.
+      if command gh api graphql -f query='{viewer{login}}' --include >"$_hdr_tmp" 2>/dev/null; then
+        # ONE HEADER READER, NOT TWO. `plot_harvest_headers` is what every
+        # harvested call already reads its bucket and numbers with, and a second
+        # implementation here is the drift `plot-pr-merged.sh` argues against —
+        # the copy that goes permissive is the one that fails unrepairably. It
+        # matches header names case-insensitively because `gh` prints
+        # `X-Ratelimit-Limit` while GitHub documents `X-RateLimit-Limit`.
+        plot_harvest_headers "$_hdr_tmp"
+        rm -f "$_hdr_tmp"
+        # A number or null — never a quoted "unknown", and never 0 standing in
+        # for absent. `jq -n` with `--argjson` refuses a non-number, so each
+        # value is tested first and passed as the literal `null` otherwise.
+        _num() { [[ "$1" =~ ^[0-9]+$ ]] && echo "$1" || echo null; }
+        if [ -n "${PLOT_BUDGET_HARVEST:-}" ]; then
+          IFS=$'\t' read -r _res _lim _rem _rst <<<"$PLOT_BUDGET_HARVEST"
+          # THE READING GOES INTO THE RECORD TOO. This call spent a request and
+          # got the connector's own numbers back, so leaving them unrecorded
+          # would throw away the one `actual` reading in the run — and
+          # `graphql_budget_spent` reads the record.
+          budget_record_call github github "${_res:-graphql}"
+          jq -cn \
+            --arg bucket "${_res:-graphql}" \
+            --argjson limit "$(_num "$_lim")" \
+            --argjson remaining "$(_num "$_rem")" \
+            --argjson reset "$(_num "$_rst")" \
+            '{connector:"github",bucket:$bucket,limit:$limit,remaining:$remaining,reset:$reset,basis:"actual"}'
+        else
+          # The call answered and carried no limit header. GitHub always sends
+          # them, so this is a proxy or an enterprise instance that strips them:
+          # unknown, and never free.
+          echo '{"connector":"github","bucket":"","limit":null,"remaining":null,"reset":null,"basis":"unknown"}'
+        fi
+      else
+        rm -f "$_hdr_tmp"
+        # A FAILED CALL IS STILL A SPENT CALL on every refusal GitHub meters, so
+        # it is recorded like any other — against `graphql`, which is what the
+        # query above spends, with no numbers.
+        budget_record_call github github graphql
+        # The host could not be asked. Exit 3 rather than printing `unknown`:
+        # *could not ask* and *asked, and it reports no limit* are different
+        # facts, and the port keeps them apart as `failed` versus an answered
+        # `unknown` reading.
+        die3 "limit: could not read the host's rate-limit headers"
+      fi
+    elif [ "$be" = "bitbucket" ]; then
+      # Bitbucket meters, and sends no `X-RateLimit-*`. So the number is this
+      # adapter's, from experience — 1000 requests/hour for an authenticated
+      # account — and it is tagged `predicted` because that is what it is.
+      #
+      # A PREDICTION IS NOT A LIE AND NOT A FAILURE. It is answered: the adapter
+      # is telling the truth about what it knows. A caller reads the basis and
+      # decides how much to trust it; a `throttled` observed during the session
+      # is what corrects it.
+      echo '{"connector":"bitbucket","bucket":"api","limit":1000,"remaining":null,"reset":null,"basis":"predicted"}'
+    else
+      echo "{\"connector\":\"$be\",\"bucket\":\"\",\"limit\":null,\"remaining\":null,\"reset\":null,\"basis\":\"unknown\"}"
+    fi
+    ;;
+
+  ci-limit)
+    # The CI connector's limit, which is a THIRD axis and does not follow the
+    # git host. This repo runs GitHub Actions on a GitHub remote; `ekzweb` runs
+    # Jenkins against Bitbucket. `ci_backend()` already resolves it separately.
+    #
+    # JENKINS IS THE `predicted` CASE THE DESIGN NAMES. A Jenkins instance
+    # reports no rate limit — there is no header and no endpoint to ask — so the
+    # ceiling is this adapter's estimate of what a shared controller tolerates,
+    # tagged for what it is. It is NOT unlimited: a Jenkins that is hammered
+    # refuses, and the refusal is what corrects the estimate.
+    _ci="$(ci_backend)"
+    case "$_ci" in
+      jenkins)
+        echo '{"connector":"jenkins","bucket":"","limit":60,"remaining":null,"reset":null,"basis":"predicted"}'
+        ;;
+      '' | none)
+        # No CI connector configured, so there is nothing to meter. An empty
+        # answer, not a limit of zero.
+        ;;
+      *)
+        # `ci_backend()` validates nothing, and neither does this — the list is
+        # open, and GitLab and Trello are named as next. A connector nobody has
+        # written an estimate for answers `unknown`, which is the honest word.
+        echo "{\"connector\":\"$_ci\",\"bucket\":\"\",\"limit\":null,\"remaining\":null,\"reset\":null,\"basis\":\"unknown\"}"
+        ;;
+    esac
+    ;;
+
+  spend-rate)
+    # WHAT HAS THIS COMPUTER SPENT, AND HOW FAST? Read back from the record
+    # every spender appends to — eleven scripts, a board, and a person at a
+    # terminal — so a caller can divide its cadence by what the account is
+    # actually spending rather than by a headcount of boards it cannot take.
+    #
+    # ONE JSON OBJECT:
+    #   {"connector":"github","account":"jwloka","bucket":"api","spent":41,
+    #    "spanMs":214000,"perHour":689.72,"lines":41,"unreadable":0,
+    #    "limit":null,"remaining":null,"resetAt":null,"basis":"unknown"}
+    #
+    # `resetAt` IS WHEN THE BUCKET REFILLS, epoch milliseconds, and it is what a
+    # caller reacting to a refusal waits for. The record has stored it since the
+    # headers were first harvested; until this slice no reader could get it back
+    # out, so the one component that needed it had to ask `gh api rate_limit` —
+    # a call that is both metered and, measured 2026-09-01, wrong.
+    #
+    # OVER THE CONNECTOR'S WINDOW, NEVER THE WHOLE FILE. Measured 2026-09-01,
+    # one board at 5 s and eleven scripts at 90 s append ~1,160 lines an hour:
+    # a rate divided by an ever-growing span approaches zero, and a cadence
+    # derived from it would relax forever — the opposite of what the record is
+    # for. The window starts at the latest reset that has already PASSED, or an
+    # hour back where no connector stated one.
+    #
+    # IT SPENDS NOTHING. This reads a file; no host is asked. That is the whole
+    # reason the record exists rather than a `rate_limit` call per decision —
+    # and `rate_limit` was measured 2026-09-01 reporting 5000 while the headers
+    # read 0, so it would be both expensive and wrong.
+    #
+    # `perHour` IS null WHERE THERE IS NO SPAN TO DIVIDE BY — one line, or
+    # several written inside one millisecond. An invented rate would be exactly
+    # the dishonest cadence input this slice exists to remove.
+    _sr_connector=""; _sr_account=""; _sr_bucket=""
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --connector) _sr_connector="${2:?}"; shift 2 ;;
+        --account) _sr_account="${2:?}"; shift 2 ;;
+        --bucket) _sr_bucket="${2:?}"; shift 2 ;;
+        *) die "spend-rate: unknown arg $1" ;;
+      esac
+    done
+    # Defaults name THIS connector and THIS account, which is what a caller
+    # asking "what am I spending?" means. An explicit triple is for a caller
+    # asking about a connector it is not itself using.
+    [ -n "$_sr_connector" ] || _sr_connector="$be"
+    [ -n "$_sr_account" ] || _sr_account="$(budget_account "$be")"
+    # AN OMITTED `--bucket` MEANS EVERY BUCKET, which is what *what am I
+    # spending?* asks. One connector meters several pools independently, and the
+    # cadence this feeds is about how fast the ACCOUNT is going — it spends both,
+    # so summing them is the honest input and naming one would ignore the
+    # traffic on the other. A caller deciding whether a POOL is spent names it.
+    _sr_rate="$(budget_rate "$_sr_connector" "$_sr_account" "$_sr_bucket")"
+    jq -c --arg connector "$_sr_connector" --arg account "$_sr_account" --arg bucket "$_sr_bucket" \
+      '{connector:$connector,account:$account,bucket:$bucket} + .' <<<"$_sr_rate"
+    ;;
+
   *)
-    die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|pr-body|rate-limit)"
+    die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|issue-status|pr-body|rate-limit|limit|ci-limit|spend-rate)"
     ;;
 esac