@plot-pm/board 0.12.0 → 0.14.0

package/plot-host.sh

@@ -8,6 +8,17 @@
 #
 # Ops (the ~6 operations plot actually needs):
 #   backend                       print the resolved backend: github|bitbucket
+#                                 REPORTS WHAT THE REPO DECLARED. An
+#                                 unrecognised `Git host` word is NOT silently
+#                                 defaulted to github — that drove a repo
+#                                 declaring `gitlab` through `gh` until
+#                                 2026-09-08. A backend this script has no arm
+#                                 for exits 4 and names the word on stderr:
+#                                 exit 4 is "this backend has no answer at
+#                                 all", a configuration a person fixes rather
+#                                 than a transient to retry. Adding a host is
+#                                 an edit to `HOST_DRIVES` and the arms below,
+#                                 and to nothing in `packages/domain`.
 #   default-branch                print the repo's default branch name
 #   pr-state <number|branch> [--repo <owner/repo>]   one JSON object:
 #                                   {"number":N,"state":"OPEN|MERGED|CLOSED|NONE",
@@ -35,6 +46,15 @@
 #                                 deciding whether to REMOVE something and
 #                                 silence is never permission. A call that
 #                                 failed outright still exits 3.
+#   pr-merge-commit <branch>       the merge commit sha of a merged PR for this
+#                                 branch, or EMPTY (exit 0) where none merged.
+#                                 The same query `pr-merged` runs, reading a
+#                                 second field of the one response. A separate
+#                                 subcommand because `pr-merged` prints one word
+#                                 and its callers read one word.
+#                                 EXIT 3 is the question failing, and it is not
+#                                 the same as an empty answer: a diff that could
+#                                 not be read is not a diff that was empty.
 #   pr-create --title T [--body B] [--base BR] [--head BR] [--draft]
 #                                 create a PR, print its URL
 #   pr-merge <number> [--squash] [--delete-branch]
@@ -85,13 +105,25 @@
 #                                 and a real failure presents identically.
 #                                 Nothing here compares runs or concludes.
 #                                 METERED: ask only for a branch already known
-#                                 to be failing. Empty on bitbucket (bb has no
-#                                 run listing) — unavailable, never "never
-#                                 failed".
+#                                 to be failing.
+#                                 DISPATCHED ON THE `CI` KEY, never on the git
+#                                 host: a build is the CI system's fact, and the
+#                                 two keys are independent. A repository that
+#                                 declared no CI, or one Plot has no connector
+#                                 for, EXITS 4 — not being able to ask is not an
+#                                 empty history.
+#                                 On jenkins it reports ONE current state as a
+#                                 history of one, with `startedAt` and `url`
+#                                 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:
+#                                 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:
 #                                   {"sha":"…","status":"queued|in_progress|
 #                                    completed|waiting|requested",
 #                                    "conclusion":"success|failure|…|null",
@@ -127,7 +159,26 @@
 #                                 unavailable, never "no run".
 #   issue-list [--limit N]        open tracker issues as JSON lines:
 #                                 {"number":N,"title":"…","url":"…",
-#                                  "createdAt":"…"}
+#                                  "createdAt":"…","status":"…",
+#                                  "statusCategory":"…"}
+#                                 `status` is the tracker's OWN word for the
+#                                 stage — per-workflow, possibly localised
+#                                 (*Internal Approving*). `statusCategory` is
+#                                 the stable three-value vocabulary (To Do /
+#                                 In Progress / Done) a board may group on.
+#                                 BOTH, because neither substitutes for the
+#                                 other: the name is what a person reads, the
+#                                 category is what a board decides on. EVERY
+#                                 backend answers both — GitHub derives them
+#                                 from the `--state` this op asks for, jira
+#                                 reads .fields.status, and bitbucket maps the
+#                                 state badge it already parses. A Jira-only
+#                                 field is what this adapter exists to prevent.
+#                                 `statusCategory` is "" where the tracker's
+#                                 vocabulary has no word for it — bitbucket's
+#                                 ON HOLD/INVALID/DUPLICATE/WONTFIX. Empty is
+#                                 an honest answer; an invented category files
+#                                 abandoned work beside finished work.
 #                                 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
@@ -366,6 +417,52 @@ host_failure_kind() { # $1=stderr text → throttled|secondary|failed
   fi
 }
 
+# --- the connector names its own repair -------------------------------------
+#
+# THE TEXT COMES FROM THE CONNECTOR THAT FAILED, never from a caller branching
+# on the stack. A refusal saying `gh auth login` is wrong advice on a Bitbucket
+# team, and it is wrong in the direction that costs most: a teammate who has not
+# read this repository runs the command they were given, it does nothing, and
+# the next step is to find a person. This connector already resolved its vendor
+# — `backend` above — so it is the one place that can name a CLI that exists.
+#
+# ONE FUNCTION RATHER THAN A TABLE AT EACH CALL SITE, and it is the connector
+# contract CLAUDE.md already states applied to words instead of budgets: only a
+# connector knows its account, its transport and its login command, so only a
+# connector may name them.
+#
+# A BACKEND THIS DOES NOT KNOW GETS NO ADVICE. Inventing a login command for an
+# unrecognised vendor is the same failure as naming the wrong one, so it says
+# what it does not know rather than guessing — the direction `host_failure_kind`
+# refuses in too.
+#
+# $1 = the backend word, as `backend` reported it.
+host_cli() { # → the CLI this backend drives, or '' where none is known
+  case "$1" in
+    github)    echo "gh" ;;
+    bitbucket) echo "bb" ;;
+    *)         echo "" ;;
+  esac
+}
+
+# The repair line for a host call that failed, on stderr, in this connector's
+# own words. Prints nothing where the vendor is unknown — see above.
+host_repair() { # $1=backend
+  local cli; cli="$(host_cli "$1")"
+  if [ -z "$cli" ]; then
+    echo "  Plot does not know which CLI drives '$1', so it cannot name the fix." >&2
+    echo "  Set 'Git host' in CLAUDE.md to a host Plot drives (github, bitbucket)." >&2
+    return
+  fi
+  if ! command -v "$cli" >/dev/null 2>&1; then
+    echo "  '$cli' is not on PATH, and this backend is driven through it." >&2
+    echo "  Install it, then: $cli auth login" >&2
+    return
+  fi
+  echo "  Check the CLI can answer: $cli auth status" >&2
+  echo "  If it is not logged in: $cli auth login" >&2
+}
+
 # A failed `pr-list`, reported and never swallowed.
 #
 # THREE OUTCOMES, KEPT APART — the rule `issue-list` states in full and this
@@ -380,13 +477,28 @@ 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}"
+      # NO REPAIR NAMED, AND THAT IS THE ANSWER. A burst refusal clears in
+      # seconds and nothing is broken, so `$cli auth login` here would send a
+      # reader to fix a login that is already fine. The decision is the wait.
+      echo "plot-host: pr-list: host refused a burst — ${err:-the host refused the request and said nothing}" >&2
+      echo "  Nothing is wrong and nothing needs fixing: this limit bounds calls at" >&2
+      echo "  once, not per hour. Retry shortly, with fewer at a time." >&2
+      exit 6
       ;;
     throttled)
-      die5 "pr-list: host throttled — ${err:-the host refused the request and said nothing}"
+      echo "plot-host: pr-list: host throttled — ${err:-the host refused the request and said nothing}" >&2
+      echo "  The window's quota is spent. Wait for the reset the message names," >&2
+      echo "  or run against an account with quota left. No login will help." >&2
+      exit 5
       ;;
   esac
-  die3 "pr-list: ${err:-the host failed the request and said nothing}"
+  # 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
+  # `host_repair`, which asks the CLI this backend drives rather than assuming
+  # one. A failure that is neither costs the reader one `auth status`.
+  echo "plot-host: pr-list: ${err:-the host failed the request and said nothing}" >&2
+  host_repair "$(backend)"
+  exit 3
 }
 
 # Run one `pr-list` host call, or die reporting which failure it was.
@@ -447,17 +559,141 @@ pr_list_call() { # "$@"=the host command → payload on stdout, or dies
 # per row rather than blanking the entire list, and exit 3 is reserved for
 # when the operation itself cannot proceed.
 
-# Resolve CI backend: $PLOT_CI (for tests), then `CI` key, default "".
-# Non-jenkins values (github-actions, none, "") mean "no separate CI fetch".
-# The CI system this repo runs its builds on: `jenkins`, `github-actions`, or
-# `none`. Independent of the Git host — a Bitbucket repo can build on Jenkins,
-# and this key is what pairs the two. `PLOT_CI` overrides for tests.
-ci_backend() {
+# The raw `CI` declaration: `$PLOT_CI`, then the `CI` key, else empty.
+#
+# `PLOT_CI` IS A PRODUCTION CONTRACT, not a test override. The function this
+# replaced called it *"overrides for tests"*, and that had been false since
+# the build connectors landed: `build-actions.ts:39` passes
+# `buildReads({ context, system: SYSTEM }, { PLOT_CI: SYSTEM })` as the dispatch
+# contract the arm reads. It keeps its precedence and is split the same way, so
+# a connector's bare `SYSTEM` word and a person's prose reach one comparison.
+ci_raw() {
   if [ -n "${PLOT_CI:-}" ]; then
-    printf '%s\n' "$PLOT_CI" | tr '[:upper:]' '[:lower:]'
+    printf '%s\n' "$PLOT_CI"
     return
   fi
-  bash "$here/plot-config.sh" get "CI" "" | tr '[:upper:]' '[:lower:]'
+  bash "$here/plot-config.sh" get "CI" ""
+}
+
+# The CI system this repository declares — the FIRST token, lowercased.
+#
+# THE ONE READER OF THE `CI` KEY'S SCHEME, and every arm that dispatches on the
+# CI system compares this. The function it replaced returned the WHOLE value
+# while its four callers each matched a bare word (`jenkins`,
+# `github-actions`), so a repository declaring
+# `` CI: Jenkins at `jenkins-ci-ewz…` `` missed every arm and read
+# `basis: unknown` where the Jenkins connector had `predicted: 60` ready.
+# Measured 2026-09-09 against a reachable instance: only the bare word matched,
+# and no repository on the estate writes it.
+#
+# THE PAYLOAD WAS THE SECOND HALF OF THAT COST. `ci-limit` reported the prose
+# value as its `connector`, and `build-shell.ts` filters readings by equality
+# against the connector's bare system word — so the reading was discarded before
+# any caller saw it, and a metered Jenkins reported as metering nothing.
+#
+# Shaped after `tracker_scheme()` (`:1340`) — the same key packing a scheme
+# ahead of its detail, split the same way. Empty when nothing is declared, and
+# ABSENT IS NOT FALSE: `ci_unaskable()` reads an empty scheme as *this
+# repository named no CI system*, which is a different answer from *this system
+# has no connector*.
+ci_scheme() {
+  ci_raw | awk '{print tolower($1)}'
+}
+
+# Whether a candidate token is a host `jen -I` could be given.
+#
+# A URL passes whole. Otherwise it must be dot-separated labels ending in an
+# alphabetic TLD, carrying no path separator and no `@`.
+#
+# THE FINAL FILTER IS THE FILE EXTENSION, and that is a measurement rather than
+# a preference. `ci.yml` and `package.json` both match the dotted-label pattern,
+# while `.ch` and `.io` are real two-letter TLDs — so TLD LENGTH cannot separate
+# a host from a filename in either direction, and a `CI:` value naming a
+# workflow file (`github-actions (see .github/workflows/ci.yml)`) is the
+# measured case that would otherwise be read as a server.
+ci_looks_like_host() {
+  case "$1" in
+    https://*|http://*) return 0 ;;
+    */*|*@*) return 1 ;;
+  esac
+  printf '%s\n' "$1" \
+    | grep -qE '^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*\.[a-z]{2,}$' || return 1
+  case "$1" in
+    *.yml|*.yaml|*.json|*.md|*.sh|*.js|*.ts|*.mjs|*.cjs|*.toml|*.xml|*.txt|*.lock|*.gradle) return 1 ;;
+  esac
+  return 0
+}
+
+# Where this repository's CI lives: the `Jenkins instance` key, then
+# `$JENKINS_INSTANCE`, then a host read out of the `CI` value. Empty when none
+# of the three names one.
+#
+# THE ORDER IS NOT THE TRACKER'S, and the reason is information content.
+# `tracker_base_url()` lets `$PLOT_JIRA_BASE_URL` win over its config value
+# because both carry the same shape — a URL. Here the key carries MORE than the
+# prose can express: `jenkins_instance()` (`:665`) returns `<slug>/<job/path>`,
+# and the container path is a fact no file in a repository states
+# (`stack.ts:98` calls the host *"the SLUG half"*). A prose-derived slug alone
+# degrades `jenkins_build_map()` to root-scope listing, where its own comment
+# says *"every branch reads `none`"* — and `quaweb` is nested
+# (`job/quaweb/job/release`), so that renders an empty board for the exact
+# repository this serves. So the explicit key is the primary and the prose is
+# the fallback, never the other way round.
+#
+# IT EXTRACTS A HOST, NOT A REMAINDER. "Everything after the first token" was
+# measured against all three real values and fails on every one:
+# `at jenkins-ci-ewz… (Bitbucket PRs…`, `pipelines in .build/pipelines/ …`,
+# `(e.g. continuous-build…)`. None is a host, and handing `jen -I` a sentence
+# is worse than handing it nothing. `Tracker:` gets away with the naive split
+# because its value is a scheme and a URL; `CI:` is prose in every repository
+# that declares it.
+#
+# A BACKTICKED SPAN IS PREFERRED because the backticks are a deliberate act —
+# the writer pointed at the value. It must still look like a host: one real
+# repository marks up a PATH (`` `.build/pipelines/` ``), which is not a server.
+#
+# BACKTICKS ARE STRIPPED AND NO SCHEME IS NORMALISED ON. `ewz` writes a bare
+# host in backticks and the probe used a full `https://` URL; `jen -I` accepts
+# either, so inventing a canonical form would break whichever caller passes the
+# other one.
+#
+# EMPTY IS AN ANSWER, not a failure: `Jenkins (e.g. continuous-build, …)` names
+# no instance. Read the exit code, never the emptiness.
+ci_instance() {
+  local instance candidate
+  instance=$(bash "$here/plot-config.sh" get "Jenkins instance" "" 2>/dev/null || echo "")
+  [ -n "$instance" ] || instance="${JENKINS_INSTANCE:-}"
+  if [ -n "$instance" ]; then
+    printf '%s' "$instance"
+    return
+  fi
+
+  local value
+  value="$(ci_raw)"
+
+  # The backticked spans, in order: `tr` puts each on its own line, so the
+  # even-numbered lines are what sat between a pair of backticks.
+  while IFS= read -r candidate; do
+    [ -n "$candidate" ] || continue
+    if ci_looks_like_host "$candidate"; then
+      printf '%s' "$candidate"
+      return
+    fi
+  done <<EOF
+$(printf '%s\n' "$value" | tr '\`' '\n' | awk 'NR % 2 == 0')
+EOF
+
+  # Otherwise the first bare token that looks like a host. Punctuation that
+  # ends a clause is split off so `(jenkins.acme.dev)` reads as the host.
+  while IFS= read -r candidate; do
+    [ -n "$candidate" ] || continue
+    if ci_looks_like_host "$candidate"; then
+      printf '%s' "$candidate"
+      return
+    fi
+  done <<EOF
+$(printf '%s\n' "$value" | tr -d '\`' | tr ' \t,()[]<>"'"'" '\n')
+EOF
 }
 
 # Fetch Jenkins build statuses for every branch in a multibranch job, in ONE
@@ -562,6 +798,56 @@ jenkins_build_map() {
   '
 }
 
+# Where this repository's Jenkins lives — the `Jenkins instance` key, else
+# `JENKINS_INSTANCE`. Prints nothing when neither is set.
+#
+# Read through ONE function because three ops now ask it. `pr-list --rich` read
+# it inline first; `runs` and `run-for-sha` ask the same question and must get
+# the same answer and the same refusal, or a repository would be configured for
+# one op and not the others.
+jenkins_instance() {
+  local instance
+  instance=$(bash "$here/plot-config.sh" get "Jenkins instance" "" 2>/dev/null || echo "")
+  [ -n "$instance" ] || instance="${JENKINS_INSTANCE:-}"
+  printf '%s' "$instance"
+}
+
+# The refusal a Jenkins op prints when it has no instance to ask, naming the
+# three repairs. Exit 3 — the op itself cannot proceed, which is a config error
+# only a person can fix, and deliberately NOT exit 4: a `CI: jenkins` repository
+# CAN be asked about builds, it just has not said where.
+jenkins_no_instance() {
+  echo "plot-host: CI is jenkins but no Jenkins instance is configured" >&2
+  echo "  Add a 'Jenkins instance' key to the ## Plot Config section of CLAUDE.md," >&2
+  echo "  naming the instance \`jen\` knows, or set JENKINS_INSTANCE." >&2
+  echo "  Or drop the 'CI: jenkins' key to read build status from the git host." >&2
+  exit 3
+}
+
+# NOT BEING ABLE TO ASK IS NOT AN EMPTY ANSWER, and exit 4 is where the two are
+# kept apart. An empty run list means *this branch has no runs*; a repository
+# that declared no CI system has nothing that could hold one, and a caller
+# reading `[]` for that would report *nothing has ever failed here* about a
+# question nobody asked.
+#
+# `ci-limit`'s `*)` arm already draws this line for a connector nobody wrote an
+# estimate for. This draws it one step earlier, for a connector that does not
+# exist at all — and `resultOf` (`adapters/run-script.ts:211`) maps exit 4 onto
+# `unaskable`, which is the word the build port already answers with.
+ci_unaskable() { # $1 = the op's name, $2 = the CI word (may be empty)
+  local ci_word="${2:-}"
+  if [ -z "$ci_word" ] || [ "$ci_word" = none ]; then
+    echo "plot-host: $1 — this repository declares no CI system, so there is nothing to ask" >&2
+    echo "  Add a 'CI' key to the ## Plot Config section of CLAUDE.md naming the" >&2
+    echo "  system that builds this repository — \`github-actions\` or \`jenkins\`." >&2
+  else
+    echo "plot-host: $1 — no connector for CI system '$ci_word'" >&2
+    echo "  Plot answers this op for \`github-actions\` and \`jenkins\`. An unknown" >&2
+    echo "  system cannot be asked, which is not the same as having no runs." >&2
+  fi
+  exit 4
+}
+
 # A LOOKUP MISS AND A TRANSPORT FAILURE ARE TWO ANSWERS, AND THE CLI GIVES ONE
 # EXIT CODE FOR BOTH.
 #
@@ -1208,6 +1494,60 @@ tracker_base_url() {
   tracker_raw | awk '{print $2}' | sed 's:/*$::'
 }
 
+# The Jira projects this repository's work lives in, one per line, or nothing.
+#
+# WHY A KEY AND NOT A QUERY. The inbox's default JQL scopes by PERSON
+# (`assignee = currentUser()`) and by STATE (`resolution = EMPTY`), and by
+# nothing else. On a shared Jira instance that is instance-wide: one reporter's
+# board showed twelve issues, of which one belonged to a different customer
+# entirely. Jira has no notion of the repository a board serves — no
+# `currentProject()` function exists — and that mapping lives only here, in this
+# repository's own config. Asking Jira which projects the user can see answers
+# the wrong question: that list is instance-wide too, and is what produced the
+# bug.
+#
+# IT HOLDS A LIST, and the single prefix adoption seeds only STARTS it.
+# `plot-detect-repo.sh` takes `head -1`, so a freshly adopted repo declares one
+# project. Filtering on that alone would be a second defect wearing the fix's
+# clothes — on the reported repository it shows 3 of 12 issues and hides the
+# other two projects' work under a heading claiming nobody had planned it. A
+# repository mapping to several Jira projects is the normal case.
+#
+# NAMED `Ticket prefixes`, not `Jira projects` (which puts a vendor in a config
+# key and severs the word the probe already uses) and not `Tracker projects`
+# (which generalises over a set of one). It sits next to `Branch prefixes` in
+# every adopting repo's config — an unrelated structural key holding `idea/`,
+# `feature/`, `bug/` — and only this docstring keeps the two apart.
+#
+# EMPTY IS THE ANSWER FOR AN UNDECLARED KEY, and callers must keep it meaning
+# *do not scope*: the absent case has to leave today's query untouched, or an
+# upgrade empties every existing board's inbox — a worse failure than the one
+# being fixed, because it looks like *no tickets* rather than the wrong ones.
+#
+# PARSING IS STATED HERE, not inherited: this is the estate's first list-valued
+# key with a consumer (`Implementation home` is documented as taking a list and
+# nothing splits one). Commas separate, surrounding whitespace is not part of a
+# value, and an empty element is dropped rather than emitted — a join over a
+# stray comma would otherwise produce `IN (PROJ-A,)`, which Jira rejects. A
+# value that is punctuation alone therefore reads as *undeclared*: it restores
+# the unscoped query rather than sending a query no instance would accept.
+#
+# `PLOT_TICKET_PREFIXES` overrides, the shape `PLOT_TRACKER` already sets. It
+# cannot express ABSENCE — an empty override falls through to the config — so
+# the absent case is tested with a repository that declares nothing.
+tracker_projects() {
+  local raw
+  if [ -n "${PLOT_TICKET_PREFIXES:-}" ]; then
+    raw="$PLOT_TICKET_PREFIXES"
+  else
+    raw="$(bash "$here/plot-config.sh" get "Ticket prefixes" "")"
+  fi
+  # One per line, trimmed, empties dropped. `plot-config.sh` already normalises
+  # `A,B` to `A, B`, but an override arrives unnormalised and a hand-edited
+  # value can carry a stray comma — so the split is done here regardless.
+  printf '%s' "$raw" | tr ',' '\n' | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//' | grep -v '^$' || true
+}
+
 # The env var scheme for Jira auth. The plan left the EXACT names open, to be
 # confirmed against a real instance; these follow Jira Cloud's documented Basic
 # scheme (email + API token, base64'd into an Authorization header):
@@ -1225,7 +1565,10 @@ jira_require_config() {
     die3 "Tracker is jira but no base URL is configured (write 'Tracker: jira https://your.atlassian.net' or set PLOT_JIRA_BASE_URL)"
   fi
   if [ -z "${JIRA_EMAIL:-}" ] || [ -z "${JIRA_API_TOKEN:-}" ]; then
-    die3 "Jira needs JIRA_EMAIL and JIRA_API_TOKEN in the environment — an unauthenticated Jira must not read as an empty inbox"
+    echo "plot-host: Jira needs JIRA_EMAIL and JIRA_API_TOKEN in the environment — an unauthenticated Jira must not read as an empty inbox" >&2
+    echo "  Create a token at https://id.atlassian.com/manage-profile/security/api-tokens" >&2
+    echo "  then export JIRA_EMAIL=<your account email> and JIRA_API_TOKEN=<the token>." >&2
+    exit 3
   fi
 }
 
@@ -1348,21 +1691,64 @@ pr_list_report_truncation() {
   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
 }
 
-backend() {
+# 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
+# host means teaching the ops below its CLI; this array is the record of which
+# have been taught, and it sits beside the arms it describes. `packages/domain`
+# holds no copy — `HostBackend` is any string, and `host-shell.ts` passes
+# through whatever this prints — so a third host is an edit here and nowhere in
+# the domain.
+HOST_DRIVES="github bitbucket"
+
+# Is this a backend the ops below can actually drive?
+host_drivable() { # $1=backend word
+  case " $HOST_DRIVES " in *" $1 "*) return 0 ;; *) return 1 ;; esac
+}
+
+# The backend this repository declared, in the word it used.
+#
+# REPORTS WHAT IT WAS TOLD, AND DEFAULTS ONLY WHERE NOTHING WAS SAID. A repo
+# declaring `Git host: gitlab` was answered `github` until 2026-09-08 — the
+# unrecognised word was discarded and the default returned in its place, so a
+# GitLab team was driven through `gh` and every refusal named a host they had
+# not configured. An absent key still defaults to github, which is the same
+# answer for the same reason: nothing was said, so nothing was discarded.
+#
+# `bb` is an ALIAS rather than an unknown word, and it normalises to bitbucket.
+backend_declared() {
   if [ -n "${PLOT_HOST:-}" ]; then
-    case "$PLOT_HOST" in
-      github|bitbucket) echo "$PLOT_HOST"; return ;;
-      *) die "unknown PLOT_HOST '$PLOT_HOST' (github|bitbucket)" ;;
-    esac
+    printf '%s\n' "$PLOT_HOST" | tr '[:upper:]' '[:lower:]'
+    return
   fi
   local v
   v="$(bash "$here/plot-config.sh" get "Git host" "github" | tr '[:upper:]' '[:lower:]')"
   case "$v" in
-    bitbucket|bb) echo "bitbucket" ;;
-    *) echo "github" ;;
+    bb) echo "bitbucket" ;;
+    "") echo "github" ;;
+    *) printf '%s\n' "$v" ;;
   esac
 }
 
+# The resolved backend, refused where this script has no arm for it.
+#
+# THE REFUSAL IS THIS LAYER'S, AND IT NAMES THE WORD. Every op below dispatches
+# on this answer, so a word with no arm must stop here rather than fall into
+# whichever branch happens to be last — that is how `gitlab` became a Bitbucket
+# call. Exit 4 says the question cannot be asked of this backend AT ALL, which
+# is what an unknown host is: not a broken call to retry, but a configuration a
+# person must fix. `host-shell.ts` reads that code as `unaskable` and reads the
+# sentence below for the name.
+backend() {
+  local v
+  v="$(backend_declared)" || return 1
+  if ! host_drivable "$v"; then
+    echo "plot-host: cannot drive '$v' — this script drives ${HOST_DRIVES// /, }; set the 'Git host' key in CLAUDE.md (or \$PLOT_HOST) to one of them" >&2
+    return 4
+  fi
+  printf '%s\n' "$v"
+}
+
 
 # --- the connector counts what it spends -----------------------------------
 #
@@ -1802,7 +2188,11 @@ jen() {
 
 op="${1:-}"; [ -n "$op" ] || die "usage: plot-host.sh <op> [args...] (see header)"
 shift
-be="$(backend)" || exit 1
+# THE BACKEND'S REFUSAL IS PASSED THROUGH, NOT FLATTENED. `backend` exits 4 for
+# a host it has no arm for, and exit 4 is the contract's "this backend has no
+# answer at all" — the one code every caller reads as permanent rather than
+# transient. Collapsing it to 1 here would tell a GitLab repo to retry forever.
+be="$(backend)" || exit $?
 
 # 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 —
@@ -2041,6 +2431,73 @@ case "$op" in
     fi
     ;;
 
+  pr-merge-commit)
+    # THE MERGE COMMIT OF A BRANCH'S MERGED PR, and nothing else.
+    #
+    # A SECOND SUBCOMMAND RATHER THAN A FIELD ON `pr-merged`, because that one
+    # prints ONE WORD and eleven callers read it as one — `plot-reap.sh`,
+    # `plot-release-refs.sh` and `plot-dispatch.sh` among them, each deciding
+    # whether to remove something. Widening its output to carry a sha would
+    # rewrite a contract those callers depend on, to serve a question none of
+    # them asks.
+    #
+    # THE QUERY IS `pr-merged`'s, so a caller asking both spends TWO calls where
+    # one would do — and that is a cost this path does not pay: delivery asks
+    # this only for a branch it has already been told merged, and the plan it
+    # serves budgets one host call per branch either way.
+    #
+    # `--state all` and `--limit 100` for `pr-merged`'s own two reasons: a
+    # merged PR reports CLOSED, and the newest PR is not the merge.
+    #
+    # PRINTS NOTHING AND EXITS 0 where no PR merged — an ANSWER, the same shape
+    # `pr-state` gives for a missing PR. Exit 3 is the question failing.
+    ref="${1:?pr-merge-commit needs a branch}"; shift || true
+    repo_args=()
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --repo) repo_args=(-R "${2:?}"); shift 2 ;;
+        *) die "pr-merge-commit: unknown arg $1" ;;
+      esac
+    done
+    if [ "$be" = "github" ]; then
+      if out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr list --head "$ref" --state all --limit 100 --json mergedAt,mergeCommit 2>/tmp/plot-host-err.$$)"; then
+        rm -f "/tmp/plot-host-err.$$"
+        # The FIRST merged PR carrying a sha. A branch may hold several merged
+        # PRs; each names its own merge commit, and any of them is a commit that
+        # landed this branch's work.
+        jq -r 'map(select(.mergedAt != null and .mergeCommit != null))
+               | map(.mergeCommit.oid) | first // empty' <<<"$out"
+      else
+        err="$(cat "/tmp/plot-host-err.$$" 2>/dev/null)"; rm -f "/tmp/plot-host-err.$$"
+        # A lookup miss is an answer: no PR, so no merge commit. Anything else
+        # is the question failing, and silence must not read as "carried
+        # nothing" — the caller distinguishes the two by the exit code.
+        if [ -z "$err" ] || is_lookup_miss "$err"; then
+          :
+        else
+          echo "plot-host: $err" >&2
+          exit 3
+        fi
+      fi
+    else
+      bb_require_json
+      # Bitbucket names the merge commit `merge_commit.hash` on a merged PR.
+      if out="$(bb ${repo_args[@]+"${repo_args[@]}"} pr list --state merged --json 2>/tmp/plot-host-err.$$)"; then
+        rm -f "/tmp/plot-host-err.$$"
+        jq -r --arg b "$ref" 'map(select(.source.branch.name==$b))
+               | map(.merge_commit.hash // empty) | first // empty' <<<"$out"
+      else
+        err="$(cat "/tmp/plot-host-err.$$" 2>/dev/null)"; rm -f "/tmp/plot-host-err.$$"
+        if [ -z "$err" ] || is_lookup_miss "$err"; then
+          :
+        else
+          echo "plot-host: $err" >&2
+          exit 3
+        fi
+      fi
+    fi
+    ;;
+
   pr-create)
     title=""; body=""; base=""; head=""; draft=0
     while [ $# -gt 0 ]; do
@@ -2154,15 +2611,12 @@ case "$op" in
     #     the board rejects a non-zero pr-list and keeps its last good map; one
     #     dead Jenkins must not darken every row. This reconciles Done-when 4's
     #     "exits 3" with the brief's "prefer unknown on the affected rows".
-    ci="$(ci_backend)"
+    ci="$(ci_scheme)"
     jen_map=""
     jen_status=""
     if [ "$ci" = "jenkins" ] && [ "$rich" = 1 ]; then
-      jen_instance=$(bash "$here/plot-config.sh" get "Jenkins instance" "" 2>/dev/null || echo "")
-      [ -n "$jen_instance" ] || jen_instance="${JENKINS_INSTANCE:-}"
-      if [ -z "$jen_instance" ]; then
-        die3 "CI is jenkins but no Jenkins instance is configured (set a 'Jenkins instance' key)"
-      fi
+      jen_instance="$(jenkins_instance)"
+      [ -n "$jen_instance" ] || jenkins_no_instance
       jen_payload=$(jenkins_build_map "$jen_instance")
       jen_status=$(printf '%s' "$jen_payload" | jq -r '.status // "failed"' 2>/dev/null || echo "failed")
       jen_map=$(printf '%s' "$jen_payload" | jq -c '.map // {}' 2>/dev/null || echo "{}")
@@ -2417,9 +2871,13 @@ case "$op" in
     # and failing branches are rare by construction; a caller that asked for
     # every branch would spend a budget the board has already exhausted once.
     #
-    # Bitbucket reports nothing here rather than something invented. `bb` has no
-    # run listing, and an empty history renders as "unavailable" — never as
-    # "this branch has never failed before".
+    # IT DISPATCHES ON THE CI SYSTEM, NEVER ON THE GIT HOST. This arm gated on
+    # `be` until 2026-09-08, which made this repository's accident — GitHub is
+    # both — the shape of the op: a Bitbucket team building on Jenkins got
+    # silence, and a GitHub team building on Jenkins got GitHub Actions runs
+    # for a repository whose CI is not GitHub Actions. `CI` and `Git host` are
+    # independent `## Plot Config` keys, and this is the op that reads the
+    # first of them.
     branch="${1:?runs needs a branch}"; shift
     limit=10
     while [ $# -gt 0 ]; do
@@ -2428,13 +2886,61 @@ case "$op" in
         *) die "runs: unknown arg $1" ;;
       esac
     done
-    if [ "$be" = "github" ]; then
-      gh run list --branch "$branch" --limit "$limit" \
-        --json workflowName,conclusion,status,startedAt,url 2>/dev/null \
-        | jq -c '.[] | {workflow:.workflowName,
-                        conclusion:(if (.conclusion // "") == "" then .status else .conclusion end),
-                        startedAt:.startedAt, url:.url}' 2>/dev/null || true
-    fi
+    _ci="$(ci_scheme)"
+    case "$_ci" in
+      github-actions)
+        # THE GIT HOST STILL HAS TO BE GITHUB, and that is a second condition
+        # rather than the same one. `gh run list` reads the runs of the
+        # repository the CWD's remote names, so a repository declaring
+        # `CI: github-actions` on a Bitbucket remote has declared something
+        # `gh` cannot reach — an unaskable configuration, not an empty history.
+        if [ "$be" != "github" ]; then
+          echo "plot-host: runs — CI is github-actions but the git host is '$be'" >&2
+          echo "  \`gh run list\` reads the runs of the repository its remote names," >&2
+          echo "  so there is no GitHub repository here to ask about." >&2
+          exit 4
+        fi
+        gh run list --branch "$branch" --limit "$limit" \
+          --json workflowName,conclusion,status,startedAt,url 2>/dev/null \
+          | jq -c '.[] | {workflow:.workflowName,
+                          conclusion:(if (.conclusion // "") == "" then .status else .conclusion end),
+                          startedAt:.startedAt, url:.url}' 2>/dev/null || true
+        ;;
+      jenkins)
+        # ONE STATE PER BRANCH, REPORTED AS A HISTORY OF ONE — and the PR says
+        # so, because it is the honest limit of the transport this arm has.
+        # `jenkins_build_map` answers `{color, checks, job}` for every branch in
+        # one call: a CURRENT state, with no timestamps, no URL and no earlier
+        # runs. A history is what Jenkins holds and what its REST API answers;
+        # reading it is `the-ci-connector-is-jenkins`'s own slice, and inventing
+        # entries here to fill the shape would be the collector reaching a
+        # verdict (Principle 3).
+        #
+        # SO THE FIELDS THIS CANNOT MEASURE ARE EMPTY, never guessed. `workflow`
+        # names the Jenkins job, which is the one thing the map does carry and
+        # the detail a reader opens; `conclusion` is the `checks` word the
+        # colour table already settled; `startedAt` and `url` are empty,
+        # because a timestamp this arm invented would read as measurement.
+        _jen_instance="$(jenkins_instance)"
+        [ -n "$_jen_instance" ] || jenkins_no_instance
+        _jen_payload=$(jenkins_build_map "$_jen_instance")
+        _jen_status=$(printf '%s' "$_jen_payload" | jq -r '.status // "failed"' 2>/dev/null || echo "failed")
+        if [ "$_jen_status" != "ok" ]; then
+          # UNREACHABLE IS NOT EMPTY EITHER. `pr-list --rich` can mark its rows
+          # `unknown` and keep them; this op has no row to carry the word, so
+          # the only way to say *cannot verify* is the exit code. Printing
+          # nothing at exit 0 would read as *this branch has never run*.
+          echo "plot-host: runs — jenkins unreachable ($_jen_status)" >&2
+          exit 4
+        fi
+        printf '%s' "$_jen_payload" | jq -c --arg branch "$branch" \
+          '.map[$branch] // empty
+           | {workflow:(.job // ""), conclusion:(.checks // ""), startedAt:"", url:""}' 2>/dev/null || true
+        ;;
+      *)
+        ci_unaskable runs "$_ci"
+        ;;
+    esac
     ;;
 
   run-for-sha)
@@ -2480,39 +2986,80 @@ case "$op" in
         *) 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
+    # DISPATCHED ON THE CI SYSTEM, for the reason `runs` above states: the git
+    # host is a separate key, and a build is the CI system's fact.
+    _ci="$(ci_scheme)"
+    case "$_ci" in
+      jenkins)
+        # JENKINS CANNOT ANSWER THIS THROUGH `jen`, AND THAT IS A MEASUREMENT
+        # RATHER THAN A GAP LEFT OPEN. `jenkins_build_map` — the only Jenkins
+        # reader this script has — answers `{color, checks, job}` per BRANCH and
+        # carries no commit at all, so there is nothing here to match a sha
+        # against.
+        #
+        # THE ANSWER EXISTS AND THIS TRANSPORT DOES NOT REACH IT. Measured
+        # 2026-09-08 against a live instance, a build names its commit at
+        # `actions[].BuildData.lastBuiltRevision.SHA1`, paired with its branch —
+        # over the REST API, which `the-ci-connector-is-jenkins` reads. Until
+        # that lands, `unaskable` is the true word: this connector cannot be
+        # asked, which is not the same as the branch having no run for the sha.
+        #
+        # FALLING BACK TO THE BRANCH'S CURRENT STATE WOULD BE THE ONE ANSWER
+        # THAT COSTS A MERGE. This op exists because a run for a superseded
+        # commit reads identically to a run for the current one, and reporting
+        # a branch-scoped state with no sha in it is exactly the guessing it was
+        # written to end — two merge waiters were stopped for it on 2026-08-30.
+        echo "plot-host: run-for-sha — jenkins has no sha-scoped answer through \`jen\`" >&2
+        echo "  \`jen job list\` reports one state per branch and names no commit." >&2
+        echo "  A build's sha is in Jenkins and reached over its REST API, which" >&2
+        echo "  the Jenkins build connector reads. Until then this cannot be asked." >&2
+        exit 4
+        ;;
+      github-actions) : ;;
+      *) ci_unaskable run-for-sha "$_ci" ;;
+    esac
+    if [ "$be" != "github" ]; then
+      # SAME SECOND CONDITION AS `runs`: `gh run list` reads the repository its
+      # remote names, so `CI: github-actions` on a non-GitHub remote names runs
+      # that cannot be reached from here.
+      echo "plot-host: run-for-sha — CI is github-actions but the git host is '$be'" >&2
+      echo "  \`gh run list\` reads the runs of the repository its remote names," >&2
+      echo "  so there is no GitHub repository here to ask about." >&2
+      exit 4
     fi
+    # From here the CI system is `github-actions` and the git host is GitHub;
+    # both were established above, so nothing guards the call.
+    # `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
     ;;
 
   issue-list)
@@ -2548,7 +3095,29 @@ case "$op" in
       # narrower inbox. ORDER BY created DESC so the newest ticket is first, the
       # same order `createdAt` gives the GitHub arm.
       jira_require_config
-      jql="${PLOT_JIRA_JQL:-assignee = currentUser() AND resolution = EMPTY ORDER BY created DESC}"
+      # `Ticket prefixes` SCOPES THE DEFAULT to this repository's projects. The
+      # default alone scopes by person and by state, so on a shared instance it
+      # is instance-wide: it returned another customer's ticket to a reporter's
+      # board (see `tracker_projects` for the measurement and the naming).
+      #
+      # THE CLAUSE IS SPLICED, NOT APPENDED, and the split below is why: JQL
+      # requires ORDER BY to close the query, so a clause added to the end of
+      # the default string makes a query Jira rejects.
+      #
+      # AN UNDECLARED KEY LEAVES THE QUERY BYTE-IDENTICAL. `$scope` is empty,
+      # the two halves rejoin exactly as they were written, and an upgrade
+      # changes nothing for a repository that never set the key.
+      scope=""
+      if projects="$(tracker_projects)" && [ -n "$projects" ]; then
+        # `IN (A, B)`, never a trailing comma: paste joins N-1 separators over N
+        # elements, so a one-element list — what adoption's seed writes — yields
+        # `IN (A)` rather than `IN (A,)`.
+        scope=" AND project IN ($(printf '%s' "$projects" | paste -sd, - | sed 's/,/, /g'))"
+      fi
+      # PLOT_JIRA_JQL STILL WINS OVER BOTH. Teams worked around this bug with
+      # their own JQL; an override that stopped overriding would break exactly
+      # the people who noticed the problem first.
+      jql="${PLOT_JIRA_JQL:-assignee = currentUser() AND resolution = EMPTY${scope} ORDER BY created DESC}"
       # maxResults bounds ONE page. The inbox is small by construction (a
       # person's open tickets), so no nextPageToken loop is needed; the caller's
       # --limit caps it, else Jira's default page. v2 `search/jql` takes the same
@@ -2560,7 +3129,7 @@ case "$op" in
       raw="$(jira_curl "/rest/api/2/search/jql" \
                -G \
                --data-urlencode "jql=$jql" \
-               --data-urlencode "fields=summary,created" \
+               --data-urlencode "fields=summary,created,status" \
                --data-urlencode "maxResults=$max")"; curl_rc=$?
       body="$(jira_check "$raw" "$curl_rc")" || exit $?
       # `number` is the Jira KEY (PROJ-123), a string — #447 taught the parser to
@@ -2568,21 +3137,39 @@ case "$op" in
       # search payload carries no browse URL, and the base is ours to know
       # (Principle 3: this script is the one place that knows a host URL's shape).
       base="$(tracker_base_url)"
+      # `status` is the workflow's own word (*Internal Approving*) and may be
+      # localised; `statusCategory` is Jira's stable three-value vocabulary
+      # (To Do / In Progress / Done). BOTH are carried because neither
+      # substitutes for the other: the name is what a person reads, the
+      # category is what a board groups on. A board grouping on the name
+      # fragments across projects that spell the same stage differently.
       printf '%s' "$body" | jq -c --arg base "$base" '.issues[]? | {
           number: .key,
           title: (.fields.summary // ""),
           url: ($base + "/browse/" + .key),
-          createdAt: (.fields.created // "")
+          createdAt: (.fields.created // ""),
+          status: (.fields.status.name // ""),
+          statusCategory: (.fields.status.statusCategory.name // "")
         }'
     elif [ "$be" = "github" ]; then
       # `gh issue list` — not `gh api /issues`. On GitHub every PR IS an issue,
       # so the REST endpoint returns both, and every open PR would arrive here
       # as a signal nobody had planned. The `gh` subcommand filters PRs out;
       # this note exists because that trap is invisible while it works.
-      if out="$(gh issue list --state open ${limit_args[@]+"${limit_args[@]}"} \
+      # `status` is DERIVED from the state this call asks for, never written
+      # twice. GitHub has no workflow states: an issue is open or closed, and
+      # this op asks for open ones only. So the state passed to `gh` is the
+      # answer, and `$gh_state` is read by both the flag and the projection —
+      # a second literal would be a copy that a widened filter silently
+      # outdates. `To Do` is the category because an open GitHub issue is
+      # unstarted by the only vocabulary GitHub has.
+      gh_state="open"
+      if out="$(gh issue list --state "$gh_state" ${limit_args[@]+"${limit_args[@]}"} \
                   --json number,title,url,createdAt 2>/tmp/plot-host-err.$$)"; then
         rm -f "/tmp/plot-host-err.$$"
-        jq -c '.[] | {number:.number,title:.title,url:(.url // ""),createdAt:(.createdAt // "")}' <<<"$out"
+        jq -c --arg status "$gh_state" \
+          '.[] | {number:.number,title:.title,url:(.url // ""),createdAt:(.createdAt // ""),
+                  status:$status,statusCategory:(if $status == "open" then "To Do" else "Done" end)}' <<<"$out"
       else
         err="$(cat "/tmp/plot-host-err.$$" 2>/dev/null)"; rm -f "/tmp/plot-host-err.$$"
         # NO empty-list fallback. `host_miss_or_fail` exists for a lookup whose
@@ -2622,15 +3209,37 @@ case "$op" in
         [[ "$line" =~ ^#0*([0-9]+)[[:space:]]+(.*)$ ]] || continue
         num="${BASH_REMATCH[1]}"
         rest="${BASH_REMATCH[2]}"
-        # Strip the leading state badge word (NEW/OPEN/RESOLVED/…) and its
-        # padding; the title starts after it.
-        rest="$(sed -E 's/^(NEW|OPEN|ON HOLD|INVALID|RESOLVED|DUPLICATE|WONTFIX|CLOSED)[[:space:]]+//' <<<"$rest")"
+        # Lift the leading state badge word (NEW/OPEN/RESOLVED/…), then strip
+        # it and its padding; the title starts after it. The badge was parsed
+        # here before and THROWN AWAY to recover the title — it is captured
+        # now rather than fetched, so this costs no extra call. ONE
+        # vocabulary, matched once: a second copy in a mapping table is a list
+        # that drifts from the one that strips.
+        state=""
+        if [[ "$rest" =~ ^(NEW|OPEN|ON\ HOLD|INVALID|RESOLVED|DUPLICATE|WONTFIX|CLOSED)[[:space:]]+(.*)$ ]]; then
+          state="${BASH_REMATCH[1]}"
+          rest="${BASH_REMATCH[2]}"
+        fi
+        # Map the badge onto the three-value category the board groups on.
+        # NEW/OPEN are unstarted; RESOLVED/CLOSED are finished. The rest —
+        # ON HOLD, INVALID, DUPLICATE, WONTFIX — get "" DELIBERATELY: they are
+        # terminal-without-being-done or started-without-progressing, and
+        # neither is a Jira category. Empty says *this vocabulary has no word
+        # for it*, which a board can render; inventing `Done` for WONTFIX
+        # would file abandoned work beside finished work.
+        case "$state" in
+          NEW|OPEN) category="To Do" ;;
+          RESOLVED|CLOSED) category="Done" ;;
+          *) category="" ;;
+        esac
         # Drop the trailing reporter: bb prints three spaces then `by <name>`.
         title="$(sed -E 's/[[:space:]]{2,}by [^[:space:]].*$//' <<<"$rest")"
         # `url` is "" — bb issue list prints none; a consumer renders the number
         # as plain text, the rule the header states.
         jq -cn --argjson number "$num" --arg title "$title" \
-          '{number:$number,title:$title,url:"",createdAt:""}'
+          --arg status "$state" --arg category "$category" \
+          '{number:$number,title:$title,url:"",createdAt:"",
+            status:$status,statusCategory:$category}'
         count=$((count + 1))
         # Honour the caller's --limit HERE: bb has no --limit, so a bound the
         # caller asked for is enforced by the adapter after parsing (Done-when 7).
@@ -2976,14 +3585,14 @@ case "$op" in
   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 against Bitbucket. `ci_scheme()` 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)"
+    _ci="$(ci_scheme)"
     case "$_ci" in
       jenkins)
         echo '{"connector":"jenkins","bucket":"","limit":60,"remaining":null,"reset":null,"basis":"predicted"}'
@@ -2993,9 +3602,15 @@ case "$op" in
         # answer, not a limit of zero.
         ;;
       *)
-        # `ci_backend()` validates nothing, and neither does this — the list is
+        # `ci_scheme()` 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.
+        #
+        # IT REPORTS THE SCHEME, never the whole `CI:` value. `build-shell.ts`
+        # filters readings by `reading.connector === shell.system`, and the
+        # system is a bare word — so a prose connector here is discarded before
+        # any caller sees it, and the port defines that empty answer as *a
+        # connector that meters nothing*.
         echo "{\"connector\":\"$_ci\",\"bucket\":\"\",\"limit\":null,\"remaining\":null,\"reset\":null,\"basis\":\"unknown\"}"
         ;;
     esac