@plot-pm/board 0.16.1 → 0.16.3

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
@@ -247,7 +297,9 @@
 #                                 list` (no --json), pinned to bb 0.6.0. EXIT 4
 #                                 narrows rather than disappears: it is the
 #                                 tracker-DISABLED case (bb answers 404/410),
-#                                 which stays *this host cannot answer* where an
+#                                 and a bb whose `--help` lists no `issue`
+#                                 command (Quatico bb), both of
+#                                 which stay *this host cannot answer* where an
 #                                 empty list would say *there are none*. A call
 #                                 that failed on an enabled tracker, or any error
 #                                 wording this adapter does not recognise, exits
@@ -281,7 +333,8 @@
 #                                 Same three outcomes as issue-list, same codes:
 #                                 BITBUCKET NOW ANSWERS via `bb issue view`
 #                                 (pinned to 0.6.0); `url` comes from the view's
-#                                 footer. EXIT 4 is the tracker-DISABLED case,
+#                                 footer. EXIT 4 is the tracker-DISABLED case
+#                                 or a bb with no `issue` command,
 #                                 EXIT 3 a lookup that failed or an unrecognised
 #                                 error. An issue that does not exist is a
 #                                 FAILURE here, not an empty body: the caller
@@ -468,11 +521,22 @@ die6() { echo "plot-host: $*" >&2; exit 6; }
 # 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
@@ -552,6 +616,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
@@ -1016,7 +1090,7 @@ bb_state_listing() { # global bb args… --state <s> --json → one JSON array
     esac
   done
   [ -n "$_st" ] || die "bb_state_listing: no --state"
-  _out="$(bb ${_args[@]+"${_args[@]}"} api "/repositories/{ws}/{repo}/pullrequests?state=$(bb_query_state "$_st")&pagelen=50")" || return $?
+  _out="$(bb ${_args[@]+"${_args[@]}"} api "/repositories/{ws}/{repo}/pullrequests?state=$(bb_query_state "$_st")&pagelen=$BB_LIST_PAGELEN")" || return $?
   printf '%s' "$_out" | jq -c '.values // []'
 }
 
@@ -2033,17 +2107,41 @@ bb_issue_exit_code() {
 # fails LOUDLY rather than silently mis-reading a column that may have moved.
 # `PLOT_BB_SKIP_VERSION_CHECK` exists for the test harness, whose stub bb has no
 # meaningful version — the parse is exercised against captured fixture text.
+#
+# A VERSION MISMATCH IS NOT ALWAYS A MOVED FORMAT. Two products share the name
+# `bb` (see the capability check below), and Quatico `bb` — 1.9.0 measured
+# 2026-10-01 — has no `issue` command at all: `bb --help` lists `pr …`,
+# `source …` and `api`. Telling it to update would suggest a fix that does not
+# exist, so a mismatch first asks `bb --help` what the CLI offers. A help text
+# that lists a `pr` command and no `issue` command is a bb that cannot be asked
+# about issues, which is exit 4 — the same answer as a disabled tracker. Any
+# other help text keeps the refusal below, exit 3. Exits 4 or 3; 0 passes.
 bb_assert_issue_version() {
   [ -n "${PLOT_BB_SKIP_VERSION_CHECK:-}" ] && return 0
   local v
   v="$(bb --version 2>/dev/null | bb_strip_ansi | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
   if [ "$v" != "$BB_ISSUE_VERSION" ]; then
+    if bb_lacks_issue_command; then
+      echo "plot-host: bb ${v:-unknown} lists no issue command — Quatico bb has none, unlike craftamap/bb — so this repository's issues cannot be read through it; declare the issue tracker with the \`Tracker\` config key" >&2
+      return 4
+    fi
     echo "plot-host: bb issue parse targets $BB_ISSUE_VERSION but found '${v:-unknown}' — refusing to mis-read a format that may have moved" >&2
     return 3
   fi
   return 0
 }
 
+# Whether `bb --help` lists commands and `issue` is not one of them. A help
+# that lists no `pr` command either is not a command listing this can read, so
+# it answers *not proven* (1) and the caller keeps its exit-3 refusal: guessing
+# 4 from unreadable help would turn a broken bb into *no issue tracker*.
+bb_lacks_issue_command() {
+  local help
+  help="$(bb --help 2>&1 | bb_strip_ansi)" || return 1
+  grep -qE '^[[:space:]]+pr([[:space:]]|$)' <<<"$help" || return 1
+  ! grep -qE '^[[:space:]]+issues?([[:space:]]|$)' <<<"$help"
+}
+
 # --- bb capability check (--json support) ------------------------------------
 #
 # TWO TOOLS SHARE THE NAME `bb`. craftamap/bb is a Go binary that does NOT
@@ -2254,6 +2352,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.
@@ -2516,27 +2655,36 @@ jira_check() {
 # `bb` returned 50 merged PRs (ids 836→787) against a repo numbering to 836, so
 # ~780 older merged PRs were invisible to the join.
 #
-# THE DETECTOR IS AGAINST THE REQUESTED LIMIT, NEVER THE CONSTANT 50. A future
-# `bb` page size of 100 must not make a truncated 100-row list report complete —
-# this plan's own defect restored. So the rule names no page size:
+# THE RULE IS `rules/listing-page.ts`'s `pagePossiblyTruncated`, and this is
+# its shell copy. `pr-list` runs on every board refresh, so the shell keeps the
+# rule rather than asking a bundle (docs/shell-and-domain.md), and
+# `packages/domain/corpus/listing-page.corpus.test.ts` holds the pair:
 #
 #   github (HONOURS --limit)  : a state is possibly truncated when it returned
-#                               AT LEAST the requested limit — the host may have
-#                               had more that the limit hid. Fewer rows than the
-#                               limit PROVES completeness.
-#   bitbucket (IGNORES --limit): `bb pr list` has no --limit and reports neither
-#                               a total nor a cursor, so it can NEVER prove
-#                               completeness for a --limit call. Any non-empty
-#                               page is therefore possibly truncated. An empty
-#                               page had nothing to truncate.
-#
-# THE PREMISE ABOVE IS ABOUT `bb pr list`, AND IT WAS ONCE WRITTEN ABOUT
-# BITBUCKET. It said the host "cannot report a total or a cursor" — true of the
-# CLI's listing and false of the REST endpoint behind it, which carries both a
-# `size` and a `next`. That mattered the moment a path existed that could ask:
-# the per-branch sweep (#333) proves completeness exactly, per branch, and this
-# detector is deliberately not asked about it (`pr_list_states`). The rule below
-# is unchanged and still governs every listing call.
+#                               AT LEAST the requested limit. Fewer rows than
+#                               the limit PROVES completeness.
+#   bitbucket (ONE FIXED PAGE): the listing ignores --limit and returns one page
+#                               per state. A page SHORTER than the page length
+#                               is the last page, so it is complete. A page AT
+#                               the length stays possibly truncated.
+#
+# THE PAGE LENGTH IS A READING, NEVER A CONSTANT THE RULE NAMES. The listing
+# asks `pagelen=$BB_LIST_PAGELEN` through `bb api`, and the length holds only
+# where that `bb` passes the query through unchanged, so it is read per version
+# from `BB_LIST_PAGE_VERSIONS` — pinned like `BB_ISSUE_VERSION`. A version
+# nobody measured has no length, and every non-empty page under it stays
+# possibly truncated: the rule never calls a page complete it cannot prove. A
+# future length of 100 is a new table entry, never a page of 50 read as short.
+#
+# Measured on `quatico/quaweb-website`: bb 1.9.0 returned 50 merged rows in one
+# request on 2026-09-30, and on 2026-10-01 answered `pagelen: 50` with 50 rows,
+# a `next` and `size: 895`. Before
+# 2026-10-01 every non-empty Bitbucket page was reported, so 20 open PRs read as
+# truncated on every refresh (#1137).
+#
+# THE PER-BRANCH SWEEP AND THE WINDOWED LISTING MAKE NO PAGE CLAIM. The sweep
+# proves completeness per branch and the window refuses a short read, so this
+# detector is not asked about either (`pr_list_states`).
 #
 # No --limit was requested → the caller accepted the host's default page and is
 # owed no report, so no existing no-limit caller's behaviour changes.
@@ -2555,21 +2703,82 @@ jira_check() {
 # future diff that teaches the scan to fall back, without moving the failure
 # into a minutes-long pulse. See the plan's Done-when item 3.
 #
+# The page length Bitbucket's plain listing asks for. `bb_state_listing` sends
+# it, and `pr_list_report_truncation` reads it as the page length only for a
+# `bb` in BB_LIST_PAGE_VERSIONS.
+BB_LIST_PAGELEN=50
+
+# The `bb` versions measured to pass `pagelen` through `bb api` unchanged,
+# space-separated. `adapters/host/listing-paging.ts` holds the same table.
+BB_LIST_PAGE_VERSIONS="1.9.0"
+
+# The page length the answering `bb` lists by, or nothing where its version is
+# not in BB_LIST_PAGE_VERSIONS. Reads the version `bb_require_json` recorded,
+# so it costs no `bb` call; a skipped capability check records no version.
+bb_list_page_length() {
+  local v="${BB_CAP_IDENTITY#*/}"
+  case " $BB_LIST_PAGE_VERSIONS " in
+    *" $v "*) printf '%s\n' "$BB_LIST_PAGELEN" ;;
+  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"
+  local be="$1" limit="$2" state="$3" count="$4" len=""
   [ -n "$limit" ] || return 0            # no --limit → no completeness claim owed
   [ "$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 pr_list_report_complete "$be" "$limit" "$state" "$count"; return 0; fi
   fi
-  # bitbucket: any non-empty page for a --limit call is unprovable, so it falls
-  # through to the report. Named per state so a future caller can resolve exactly
-  # the states that were capped, not a whole-call flag that over-reports.
+  # 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
@@ -3599,6 +3808,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
@@ -3623,6 +3836,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:>"`,
@@ -3701,6 +3930,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":
@@ -3840,12 +4120,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
@@ -4266,7 +4559,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).
@@ -4444,7 +4749,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.
       #

package/plot-monitor-subject.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Plot helper: the ONE answer to "is this monitor's subject still there?"
 #
-# SOURCED, NOT RUN, by `plot-worker-monitor.sh` and `plot-agent-monitor.sh`.
+# SOURCED, NOT RUN, by `plot-agent-monitor.sh` and `plot-build-monitor.sh`.
 # Both need the same computation and neither renders it the same way, which is
 # the same shape as `plot-worker-state.sh` and `plot-pr-merged.sh` — and the
 # same reason. `plot-worker-state.sh` carried five of its six states in
@@ -132,9 +132,19 @@ plot_monitor_subject() {
   pid=$(cat "$pid_file" 2>/dev/null | tr -d ' \n')
 
   # A file that exists but holds no digits is a half-written pid, which is the
-  # startup window caught mid-`printf`. Not gone.
+  # startup window caught mid-`printf`. Not gone — UNLESS the wrapper has
+  # already recorded an exit beside it. `start_worker` removes that record
+  # before every start, so in the startup window it is absent. A worker loop
+  # that moves to a new desk empties the pid file it leaves
+  # (`move_worker_record`), and the wrapper still writes the exit into this
+  # desk when the loop ends; without this arm a monitor watching that desk
+  # would read `starting` forever.
   case "$pid" in
-    '' | *[!0-9]*) printf 'starting'; return 0 ;;
+    '' | *[!0-9]*)
+      if [ -f "$(dirname "$pid_file")/.plot-worker.exit" ]; then
+        printf 'gone'; return 0
+      fi
+      printf 'starting'; return 0 ;;
   esac
 
   if kill -0 "$pid" 2>/dev/null; then
@@ -192,3 +202,45 @@ plot_monitor_wait() { # $1 = seconds to wait, $2 = pid file
   done
   return 0
 }
+
+# ═══════════════════════════════════════════════════════════════════════════
+# WHICH DESK A MONITOR WATCHES THIS PASS, AFTER A HOP MAY HAVE MOVED ITS AGENT
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# `PLOT_WORKTREE` is fixed at launch, but `update_manifest_on_hop` rewrites the
+# manifest's `worktree` field when the loop cuts a new desk — so a monitor that
+# never re-reads it watches the launch desk forever. This is the shell twin of
+# `watchedDesk` in `packages/domain/src/rules/desk-manifest.ts`, duplicated
+# rather than called for the reason `docs/shell-and-domain.md` gives: both
+# monitors re-read this every pass (30 s and 300 s), and a 39 ms bundle hop paid
+# on every pass forever is the cost the shell side exists to avoid.
+# `desk-manifest.corpus.test.ts` holds the pair; a disagreement stops the
+# branch rather than being adjusted away.
+#
+# `$1` = the manifest file this monitor was handed (`PLOT_MANIFEST_FILE`), may
+# be empty or absent.
+# `$2` = the desk this monitor was launched on (`PLOT_WORKTREE`).
+# Prints the desk to watch THIS pass.
+plot_watched_desk() { # $1 = manifest file, $2 = launch desk → prints the watched desk
+  local manifest_file="${1:-}" launched="${2:-}" field
+  # ABSENT IS NOT FALSE. No manifest file named, or one that is gone, both mean
+  # "watch what you were launched on" — never a crash and never "watch
+  # nothing". A hand-started monitor with no `PLOT_MANIFEST_FILE` is a supported
+  # shape, not an error.
+  if [ -n "$manifest_file" ] && [ -f "$manifest_file" ]; then
+    # Same grep-and-sed idiom `plot_manifest_for_worktree` uses: the manifest is
+    # pretty-printed one field per line, so this avoids parsing JSON in bash.
+    field=$(grep -m1 '"worktree":' "$manifest_file" 2>/dev/null | sed 's/.*"worktree": *"\([^"]*\)".*/\1/')
+  else
+    field=''
+  fi
+  # Whitespace-only reads as absent too, matching the rule: trim leading and
+  # trailing space before testing for emptiness.
+  field="${field#"${field%%[![:space:]]*}"}"
+  field="${field%"${field##*[![:space:]]}"}"
+  if [ -n "$field" ]; then
+    printf '%s' "$field"
+  else
+    printf '%s' "$launched"
+  fi
+}