@plot-pm/board 0.16.2 → 0.17.0

package/plot-host.sh

@@ -71,7 +71,54 @@
 #   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]
+#   pr-list [--state open|merged|closed|all] [--limit N] [--rich|--rich-open]
+#                                 --rich-open asks the rich fields of the OPEN
+#                                 pull requests only, and emits every row in the
+#                                 --rich shape. A MERGED or CLOSED row carries
+#                                 checks:"unknown", mergeable:"unknown",
+#                                 review:"" and failing_checks:[] — the ABSENT
+#                                 values the Bitbucket arm already emits, which
+#                                 mean NOT ASKED and never "no checks".
+#                                 WHY: the four rich fields are verdicts about a
+#                                 PR's HEAD, and a terminal head is finished —
+#                                 no check will run against it and no review will
+#                                 change. Measured 2026-10-01 on this
+#                                 repository, `--rich --state all --limit 1000`
+#                                 took 43.0 s against 7.3 s without the rich
+#                                 fields, and all 1000 rows were terminal, so
+#                                 36 s bought answers nobody can use.
+#                                 Re-measured 2026-10-02 with 3 PRs open:
+#                                 `--rich --state open` 2.6-3.3 s, `--state all`
+#                                 8.6-10.5 s, the split read 12.2-13.5 s.
+#                                 ON GITHUB IT IS TWO CALLS and the terminal
+#                                 rows come from the plain one; a PR open in both
+#                                 payloads is emitted once, from the rich call.
+#                                 A FAILURE IN EITHER CALL PRINTS NO ROWS AND
+#                                 EXITS NON-ZERO — a half answer reported as
+#                                 whole is what would let a caller fold a store
+#                                 that lost every open PR.
+#                                 ON BITBUCKET IT ANSWERS EXACTLY AS --rich,
+#                                 because that arm asks the host no verdict: its
+#                                 rows are already `unknown` whatever the state,
+#                                 so there is no second call to save.
+#                                 THE CALLER STILL ASKS ONCE. One `pr-list`
+#                                 invocation is one host question however many
+#                                 calls this makes, so a caller's per-refresh
+#                                 arithmetic is unchanged.
+#                                 `--limit` BOUNDS EACH CALL, NOT THE UNION, so
+#                                 the row count can exceed it by up to the number
+#                                 of open pull requests. Measured 2026-10-02 with
+#                                 5 open: `--limit 5` answered 6 rows, where
+#                                 `--rich` answered 5 — the open call returned an
+#                                 open PR that fell outside the plain call's
+#                                 newest-5 page. It is NOT bounded per call and
+#                                 then trimmed, because trimming would drop
+#                                 either a verdict the rich call just bought or a
+#                                 terminal row the store needs, and the caller
+#                                 cannot say which. Harmless where `--limit`
+#                                 exceeds the open count, which is every caller
+#                                 today: the board asks 1000 against 5 open, and
+#                                 no other caller passes this flag.
 #                                 [--since <iso>] narrows the listing to pull
 #                                 requests the host has seen change since that
 #                                 stamp. Measured 2026-09-21 on this repository:
@@ -86,16 +133,19 @@
 #                                 two seconds fast excludes the PRs updated in
 #                                 that gap from every later window — forever,
 #                                 because the window never reopens.
-#                                 GITHUB NARROWS AND BITBUCKET'S BULK LISTING
-#                                 CANNOT. `gh pr list` takes `--search`; `bb pr
-#                                 list` has no query flag at all (verified
-#                                 against bb 1.9.0: `unknown flag: --query`), so
-#                                 only the per-branch sweep's REST `q=` can
-#                                 carry it. The bulk Bitbucket listing SAYS it
-#                                 could not narrow and answers in full, because
-#                                 a full answer reported as a delta is what
-#                                 would let a caller advance a watermark over a
-#                                 window it never applied.
+#                                 BOTH HOSTS NARROW, BY DIFFERENT ROUTES.
+#                                 `gh pr list` takes `--search`. `bb pr list`
+#                                 has no query flag (verified against bb 1.9.0:
+#                                 `unknown flag: --query`), so a windowed
+#                                 Bitbucket listing goes through
+#                                 `bb_window_listing`, which asks REST with
+#                                 `q=state="..." AND updated_on>="..."` and
+#                                 walks every page. It refuses a window whose
+#                                 rows fall short of the server's `size` rather
+#                                 than printing it as whole: a full answer
+#                                 reported as a delta is what would let a caller
+#                                 advance a watermark over a window it never
+#                                 applied.
 #                                 [--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
@@ -169,13 +219,11 @@
 #                                 empty: `jen job list` carries no history and
 #                                 no timestamps, and inventing them would be a
 #                                 collector reaching a verdict.
-#   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. Dispatched on the `CI` key
-#                                 like `runs`, and EXITS 4 on jenkins: `jen job
-#                                 list` names no commit, so there is nothing to
-#                                 match a sha against. Output:
+#   run-for-sha <branch> <sha>    the run for ONE sha, and nothing for any
+#                                 other sha — as a single JSON object, or
+#                                 nothing when the branch has no run for this
+#                                 sha. Dispatched on the `CI` key like `runs`.
+#                                 Output:
 #                                   {"sha":"…","status":"queued|in_progress|
 #                                    completed|waiting|requested",
 #                                    "conclusion":"success|failure|…|null",
@@ -185,22 +233,12 @@
 #                                 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.
+#                                 the newest commit. A run for any sha but the
+#                                 one asked about is not evidence about it, so
+#                                 reporting it would invite 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.
 #                                 `status` AND `conclusion` ARE BOTH REPORTED,
 #                                 never collapsed. A run that is `completed` has
 #                                 a conclusion; one that is `waiting` or
@@ -424,7 +462,6 @@ die3() { echo "plot-host: $*" >&2; exit 3; }
 # 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.
@@ -447,7 +484,6 @@ die5() { echo "plot-host: $*" >&2; exit 5; }
 #
 # 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`
@@ -464,18 +500,29 @@ die6() { echo "plot-host: $*" >&2; exit 6; }
 # `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
+# now its own answer: `pr_list_failed` exits 6 for 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
+#
+# FOUR ANSWERS, NOT THREE — #1087: a GraphQL 504 matched neither limit pattern,
+# so it came back `failed`, and `failed` is the one kind a command fixes —
+# `gh auth login`, wrong advice for a server that took too long to answer.
+# `timeout` is anchored on the HTTP status word (`HTTP 50[234]`), never a bare
+# `\b504\b`, which would match a run id or a line count just as well. It runs
+# AFTER both limit arms: a rate-limit message that also carries a 5xx status
+# must stay `throttled`, because patience until the reset is the right advice
+# for it, and `timeout` would counsel exactly the wrong patience — none.
+host_failure_kind() { # $1=stderr text → secondary|throttled|timeout|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
+  elif LC_ALL=C grep -qiE "HTTP 50[234]|couldn.t respond to your request in time" <<<"$1"; then
+    echo timeout
   else
     echo failed
   fi
@@ -555,6 +602,16 @@ pr_list_failed() { # $1=stderr text
       echo "  or run against an account with quota left. No login will help." >&2
       exit 5
       ;;
+    timeout)
+      # NO REPAIR NAMED, FOR THE SAME REASON SECONDARY NAMES NONE — #1087. A
+      # 504 means the server took too long, not that the credential is bad, so
+      # `host_repair`'s `gh auth login` would send a reader to fix a login
+      # that was never broken. The decision is to ask again, not to log in.
+      echo "plot-host: pr-list: host timed out — ${err:-the host took too long and said nothing}" >&2
+      echo "  Nothing is wrong with the login: the server took too long to answer." >&2
+      echo "  The next refresh asks again." >&2
+      exit 3
+      ;;
   esac
   # THE ONE KIND A COMMAND FIXES. An auth gap and a DNS blip both land here, and
   # the repair for the first is a login this connector can name — see
@@ -580,7 +637,7 @@ pr_list_failed() { # $1=stderr text
 #
 # 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
+# subshell — so the `exit` inside `pr_list_failed`/`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
@@ -2281,6 +2338,47 @@ tracker_scheme() {
   tracker_raw | awk '{print tolower($1)}'
 }
 
+# WHO ANSWERS THE OPEN-ISSUE LIST — the domain's answer, not this script's.
+#
+# `issue-list` and `issue-view` tested `tracker_scheme = jira` and sent every
+# other scheme to the git host. That test was a DRIFTED SECOND COPY of the rule:
+# measured 2026-10-01, `PLOT_HOST=github PLOT_TRACKER=linear issue-list` exited 0
+# having called `gh issue list`, so a repository tracking in Linear was shown
+# GitHub's issues under Linear's name — a list not wrong about any single row
+# and wrong about all of them.
+#
+# So the rule is ASKED rather than re-implemented. `issueSource` has eight unit
+# tests and the board already asks it (`fleet.ts:2369-2380`); a lister list in
+# shell would be the same copy one directory over, free to drift again the first
+# time a connector is added.
+#
+# THE ONE NODE HOP THIS SCRIPT MAKES, and the cost rule permits it: `plot-host.sh`
+# runs once per operator command or once per board PR refresh, never once per
+# agent per pass, and a shipped bundle answers in 39 ms
+# (`docs/shell-and-domain.md`).
+#
+# Prints the entry's line verbatim — `tracker\t<scheme>`, `git-host`, or
+# `nobody\t<reason>` — and exits 0. Exits 1, naming the entry, when the rule
+# CANNOT BE ASKED: no node, no bundle, a non-zero exit, or a word outside the
+# three. THAT CASE NEVER FALLS THROUGH TO THE GIT HOST — the fall-through is
+# the defect, and `an-outage-is-not-an-answer` is what a list saying *none*
+# because it could not ask reproduces.
+issue_source() {
+  local out rc
+  out="$(tracker_raw | node "$here/board/plot-issue-source.mjs" "$be" 2>/dev/null)"; rc=$?
+  if [ "$rc" -ne 0 ]; then
+    echo "plot-host: cannot ask board/plot-issue-source.mjs who lists this repository's issues (exit $rc); the question failed and the git host is not asked in its place" >&2
+    return 1
+  fi
+  case "${out%%$'\t'*}" in
+    tracker|git-host|nobody) printf '%s\n' "$out" ;;
+    *)
+      echo "plot-host: board/plot-issue-source.mjs answered '${out}', which is not one of tracker/git-host/nobody; the question failed and the git host is not asked in its place" >&2
+      return 1
+      ;;
+  esac
+}
+
 tracker_base_url() {
   # The base URL is the SECOND token; a bare `jira` with no URL yields "".
   # PLOT_JIRA_BASE_URL overrides, for a caller that has the URL separately.
@@ -2610,6 +2708,29 @@ bb_list_page_length() {
   esac
 }
 
+# A PAGE THAT IS PROVABLY WHOLE SAYS SO, and that sentence is the licence a
+# joining caller needs. This reported only truncation until 2026-10-02: a
+# complete page was SILENT, so a caller could not tell "this page holds every
+# PR" from "this adapter has no opinion", and the only reading left to it was
+# the page's own row count against its own limit. That is a coincidence rather
+# than evidence — measured on this repository, `--state all --limit 1000`
+# returned exactly 1000 rows of 1064 PRs, so the count-based test failed, the
+# scan's `.list-complete` was withheld, and every branch the join did not name
+# fell through to one `pr-state` call each: 26 calls at 3.8 s, 54-61% of the
+# scan's wall time in slice 1's five runs (#1017).
+#
+# THE CLAIM IS THE ADAPTER'S BECAUSE THE PAGING SEMANTICS ARE. Whether a short
+# page proves anything depends on how the host pages, which is exactly what
+# this script knows and a caller does not. `pr_sweep_report` already states its
+# own stronger claim in this shape and `plot-fleet-scan.sh` already reads that
+# sentence; this is the same contract for the second path, so a listing is no
+# longer the one answer a caller has to guess at.
+#
+# BOTH SENTENCES OR NEITHER. The complete and truncated reports are the two
+# outcomes of one decision, so they are emitted from one place: a reader can
+# never see both for one state, and silence now means only that no claim was
+# owed — no `--limit`, or an empty page.
+#
 # $1 backend  $2 requested limit (may be "")  $3 state word  $4 row count
 pr_list_report_truncation() {
   local be="$1" limit="$2" state="$3" count="$4" len=""
@@ -2617,17 +2738,33 @@ pr_list_report_truncation() {
   [ "$count" -gt 0 ] 2>/dev/null || return 0   # an empty page had nothing to hide
   if [ "$be" = "github" ]; then
     # github honours the limit: complete unless the page came back AT the limit.
-    [ "$count" -ge "$limit" ] 2>/dev/null || return 0
+    # Measured 2026-10-02 on this repository (1064 PRs): `--limit 1100`
+    # answered 1065 rows and `--limit 2000` the same 1065, so a page short of
+    # its limit is the whole list and asking generously costs the rows that
+    # exist rather than the rows requested.
+    if [ "$count" -lt "$limit" ] 2>/dev/null; then pr_list_report_complete "$be" "$limit" "$state" "$count"; return 0; fi
   else
     # A fixed page: complete below a measured page length, unprovable otherwise.
     [ "$be" = "bitbucket" ] && len="$(bb_list_page_length)"
-    if [ -n "$len" ] && [ "$count" -lt "$len" ] 2>/dev/null; then return 0; fi
+    if [ -n "$len" ] && [ "$count" -lt "$len" ] 2>/dev/null; then pr_list_report_complete "$be" "$limit" "$state" "$count"; return 0; fi
   fi
   # Named per state so a caller can resolve exactly the states that were
   # capped, not a whole-call flag that over-reports.
   echo "plot-host: $be pr-list state=$state possibly truncated ($count rows, requested limit $limit unprovable) — a join against this page may read older branches as 'no PR' (#333)" >&2
 }
 
+# THE WORDING IS A CONTRACT between this script and `plot-fleet-scan.sh`, pinned
+# on both sides exactly as `pr-list sweep complete` is. A page that cannot prove
+# itself whole never prints it, so a match is licence and a miss is silence —
+# never a guess.
+#
+# PER STATE, like the truncation report beside it, because the scan asks for two
+# states and joins both: a caller needs to know which pages were whole, not that
+# some were.
+pr_list_report_complete() { # $1 backend  $2 limit  $3 state word  $4 row count
+  echo "plot-host: $1 pr-list state=$3 page complete ($4 rows below requested limit $2) — this page holds every pull request the host has in this state" >&2
+}
+
 # The backends this script has an arm for, which is what "drivable" means here.
 #
 # THE LIST LIVES IN THE SCRIPT BECAUSE THE SCRIPT IS WHAT WOULD CHANGE. Adding a
@@ -3657,6 +3794,10 @@ case "$op" in
   pr-list)
     state="open"
     rich=0
+    # Whether the rich fields are asked of the OPEN pull requests only. Set by
+    # `--rich-open`, which also sets `rich`: the flag narrows what is ASKED and
+    # never what is emitted.
+    rich_open=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
@@ -3681,6 +3822,22 @@ case "$op" in
         --state) state="${2:?}"; shift 2 ;;
         --limit) limit="${2:?}"; shift 2 ;;
         --rich) rich=1; shift ;;
+        # THE RICH FIELDS OF THE OPEN PRs AND THE PLAIN FIELDS OF THE REST.
+        # Measured 2026-10-01 on this repository: `--rich --state all --limit
+        # 1000` took 43.0 s and the same call without the rich fields took 7.3 s,
+        # while all 1000 rows were terminal — so 36 s bought four verdicts about
+        # heads nobody can act on. Re-measured 2026-10-02 with 3 PRs open:
+        # `--rich --state open` is 2.6-3.3 s and `--state all` is 8.6-10.5 s.
+        #
+        # IT IMPLIES `--rich`, so every row carries every rich field and no
+        # consumer has to ask which call produced it. A terminal row's verdicts
+        # arrive at the ABSENT values the Bitbucket arm already emits, which the
+        # store's schema accepts — so no `PR_INDEX_VERSION` bump follows.
+        #
+        # THE SPLIT IS ONLY WORTH MAKING OVER A SET THAT HOLDS TERMINAL ROWS.
+        # With `--state open` asked, both calls would list the same PRs and the
+        # second would be waste, so this collapses to plain `--rich` there.
+        --rich-open) rich=1; rich_open=1; shift ;;
         --repo) repo_args=(-R "${2:?}"); shift 2 ;;
         # `${2:?}` REFUSES AN EMPTY VALUE, and that is the point rather than
         # boilerplate. `--since ""` would reach GitHub as `--search "updated:>"`,
@@ -3759,6 +3916,57 @@ case "$op" in
     fi
 
     if [ "$be" = "github" ]; then
+      # THE SPLIT READ, AND IT IS TWO CALLS BECAUSE THE COST IS PER ROW.
+      # `gh pr list` pages internally and takes no page-size flag, so 1000 rich
+      # rows cost 1000 rows' worth of `statusCheckRollup` whatever the page.
+      # Narrowing the SET is the only lever: the rich fields are asked of the
+      # open pull requests, and everything else comes back plain.
+      #
+      # ORDER MATTERS — THE RICH ROWS GO FIRST. A PR that is open appears in
+      # both payloads, and a consumer keyed by number takes the last line it
+      # read; the second call is filtered to the terminal states instead, so no
+      # number is emitted twice and no rich row is overwritten by a plain one.
+      # Filtered rather than ordered, because a caller that sorts or de-dupes
+      # differently must not be able to reach a different answer.
+      #
+      # ASKED ONLY WHERE THE SET CAN HOLD A TERMINAL ROW. With `--state open`
+      # the two calls would list the same PRs, so this collapses to `--rich`.
+      if [ "$rich_open" = 1 ] && [ "$state" != "open" ]; then
+        # THE OPEN HALF, RICH. Asked with the caller's own `--limit` and
+        # `--since`: a window the caller set applies to both halves, or the two
+        # would answer about different populations.
+        #
+        # `|| exit $?` ON BOTH, and the rule `pr_list_call`'s header states is
+        # what makes it load-bearing here too: this runs in a command
+        # substitution, so a `die` inside leaves only that subshell and the
+        # outer script would carry on with an empty payload. A failing open call
+        # and a failing all call must each exit non-zero and print no rows.
+        _rich_open_out="$("$0" pr-list --rich --state open \
+          ${limit:+--limit "$limit"} ${since:+--since "$since"} \
+          ${repo_args[1]+--repo "${repo_args[1]}"} \
+          $(for _b in $branches; do printf -- '--branch %s ' "$_b"; done))" || exit $?
+        # THE REST, PLAIN, AND THE TERMINAL ROWS ARE THE ONES KEPT. `--state
+        # all` is asked rather than merged+closed separately: GitHub answers it
+        # in one call, and two calls would double a cost this exists to halve.
+        _plain_all_out="$("$0" pr-list --state "$state" \
+          ${limit:+--limit "$limit"} ${since:+--since "$since"} \
+          ${repo_args[1]+--repo "${repo_args[1]}"} \
+          $(for _b in $branches; do printf -- '--branch %s ' "$_b"; done))" || exit $?
+        [ -n "$_rich_open_out" ] && printf '%s\n' "$_rich_open_out"
+        # THE ABSENT VALUES ARE THE BITBUCKET ARM'S, not invented here: a
+        # terminal row carries every field a rich row carries, so one shape
+        # reaches every consumer. `checks:"unknown"` means NOT ASKED and never
+        # *no checks* — the board's fold takes the verdict it already holds for
+        # the same number, and a row with none reads as unavailable.
+        #
+        # `draft`, `url` and `updatedAt` are REAL here — the plain GitHub arm
+        # asks for them — so only the four verdicts are absent.
+        [ -n "$_plain_all_out" ] && printf '%s\n' "$_plain_all_out" \
+          | jq -c 'select(.state=="MERGED" or .state=="CLOSED")
+              | . + {checks:"unknown", mergeable:"unknown", review:"",
+                     failing_checks:[]}'
+        exit 0
+      fi
       if [ "$rich" = 1 ]; then
         # `checks` has FOUR states, and two of them mean "a person is the
         # blocker" rather than "a machine is busy":
@@ -3898,12 +4106,25 @@ case "$op" in
               }'
         fi
       else
+        # `isDraft`, `url` AND `updatedAt` TRAVEL ON THE PLAIN ARM TOO, and they
+        # are cheap: measured 2026-09-21, `number,updatedAt` over 937 PRs is
+        # 4715 ms against 5417 ms for the base fields, where
+        # `statusCheckRollup` alone is 18 842 ms. They are scalar columns on the
+        # PR node; the rollup is a per-row resolution, and that is the whole
+        # 36 s `--rich-open` removes.
+        #
+        # ASKED HERE BECAUSE `--rich-open`'S TERMINAL ROWS COME THROUGH THIS
+        # ARM, and a terminal row must carry every field a rich row carries —
+        # `updatedAt` most of all, since it is the field a durable store
+        # advances its watermark by. Without it a split full read would leave
+        # the store unable to narrow and the daily full read would never fall
+        # due against anything but a cold window.
         _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
-          --json number,title,state,headRefName,author)" || exit $?
+          --json number,title,state,headRefName,isDraft,url,updatedAt,author)" || exit $?
         pr_list_report_truncation github "$limit" "$state" \
           "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
         printf '%s' "$_gh_raw" \
-          | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,author:(.author.login // "")}'
+          | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),author:(.author.login // "")}'
       fi
     else
       # `author` IS THE `nickname`, the one handle field a Bitbucket user
@@ -4114,7 +4335,7 @@ case "$op" in
     ;;
 
   run-for-sha)
-    # The newest run for ONE sha — the BuildMonitor's only host question.
+    # The run for ONE sha, or nothing — 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
@@ -4141,9 +4362,9 @@ case "$op" in
     # 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".
+    # A Bitbucket remote exits 4 (`bb` has no run listing), as does a failing
+    # `gh` or Jenkins that cannot be asked: exit 4 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
@@ -4232,10 +4453,9 @@ case "$op" in
           echo "plot-host: run-for-sha — Jenkins did not answer for '$_jen_host'" >&2
           exit 4
         fi
-        # THE SAME FALLBACK RULE AS THE GITHUB ARM, and it is inherited rather
-        # than invented: the asked-for sha if a build carries it, else the
-        # newest build, and `sha` says WHICH. A caller that could not tell the
-        # two apart would be back to the branch-scoped guessing this op ends.
+        # THE SAME MATCH RULE AS THE GITHUB ARM: only the asked-for sha, never
+        # another build's. A build for any other commit is not evidence about
+        # this one, so no match means no output.
         #
         # `result` is null while a build runs, which is Jenkins' own word for
         # *in flight* — mapped to the `status`/`conclusion` split the contract
@@ -4247,7 +4467,7 @@ case "$op" in
                 conclusion: (if .building then null else (.result // null) end),
                 url: (.url // ""),
                 startedAt: (if .timestamp then (.timestamp / 1000 | todate) else "" end) } ]
-          | ((map(select(.sha == $sha)) | .[0]) // .[0])
+          | (map(select(.sha == $sha)) | .[0])
           | select(. != null)' 2>/dev/null || true
         # THIS ARM ANSWERS AND THE OP IS OVER. Everything below the `esac` is
         # the GitHub path — the old jenkins arm reached it only because it
@@ -4277,30 +4497,24 @@ case "$op" in
     # 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.
+    # ONLY THE ASKED-FOR SHA, NEVER ANOTHER ONE'S RUN. A run for any other
+    # commit is not evidence about this one — reporting it would read as a
+    # live answer for a commit the branch has already moved past, which is
+    # worse than no answer. No match means no output, read the same as a
+    # branch with no runs at all.
     #
-    # 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
+    # A FAILING `gh` IS NOT AN EMPTY HISTORY. An expired token, a rate limit or
+    # a network failure exits 4 here, the way the Jenkins arm does, so the
+    # monitor reads *could not ask* and not *no run yet*.
+    _gh_runs=$(gh run list --branch "$branch" --limit "$limit" \
+      --json headSha,conclusion,status,startedAt,url 2>/dev/null) \
+      || { echo "plot-host: run-for-sha — gh run list failed for '$branch'" >&2; exit 4; }
+    printf '%s' "$_gh_runs" | jq -c --arg sha "$sha" \
+      '(map(select(.headSha == $sha)) | .[0]) | select(. != null)
+       | {sha:.headSha, status:.status,
+          conclusion:(if (.conclusion // "") == "" then null else .conclusion end),
+          url:.url, startedAt:.startedAt}' || exit 4
     ;;
 
   issue-list)
@@ -4324,7 +4538,19 @@ case "$op" in
     done
     limit_args=()
     [ -n "$limit" ] && limit_args=(--limit "$limit")
-    if [ "$(tracker_scheme)" = "jira" ]; then
+    # WHO LISTS THESE ISSUES IS ASKED ONCE, HERE, BEFORE THE ARMS — after the
+    # argument parsing, so a caller's typo is still reported as a usage error
+    # rather than as a tracker refusal. The arms below then dispatch on the
+    # ANSWER, never on a second reading of the config.
+    source_said="$(issue_source)" || exit 1
+    if [ "${source_said%%$'\t'*}" = "nobody" ]; then
+      # Exit 4, the code this op already documents as *this host cannot be
+      # asked at all* — a configuration a person fixes, not a call to retry.
+      # NOTHING HAS BEEN SPENT: no `gh`, no `bb`, no curl has run yet.
+      echo "plot-host: ${source_said#*$'\t'}" >&2
+      exit 4
+    fi
+    if [ "$source_said" = $'tracker\tjira' ]; then
       # Jira, resolved through the REST API — DISPATCHED ON `Tracker`, never on
       # `backend()`: a Bitbucket repo tracking in Jira is the normal enterprise
       # case, so the git host is irrelevant here (see the Jira helpers up top).
@@ -4502,7 +4728,15 @@ case "$op" in
     # 4 to `unsupported` and anything else to `failed` must not need a second
     # table to read this op.
     num="${1:?issue-view needs an issue number}"; shift
-    if [ "$(tracker_scheme)" = "jira" ]; then
+    # Asked once, before the arms, exactly as issue-list does — the same
+    # question with the same three answers and the same exit codes. A consumer
+    # that maps 4 to `unsupported` needs no second table to read this op.
+    source_said="$(issue_source)" || exit 1
+    if [ "${source_said%%$'\t'*}" = "nobody" ]; then
+      echo "plot-host: ${source_said#*$'\t'}" >&2
+      exit 4
+    fi
+    if [ "$source_said" = $'tracker\tjira' ]; then
       # Jira, dispatched on `Tracker` not `backend()` — the same rule issue-list
       # follows. `num` is a Jira KEY (PROJ-123), read off issue-list moments ago.
       #