@plot-pm/board 0.17.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/plot-config.sh CHANGED
@@ -150,10 +150,12 @@
150
150
  # Agent max turns turns one SDK run may take. Absent = 150.
151
151
  # Slice max runs SDK runs one slice may start. Absent = 12.
152
152
  # Agent context window an SDK run's `autoCompactWindow`. Absent = 200000.
153
- # Agent max spend dollars one SDK run may spend (`maxBudgetUsd`); the
154
- # run then ends `spend-limit`. Absent = no limit, never 0.
155
- # Slice max spend dollars one slice's runs may total, read from the
156
- # slice-spend record before each run. Absent = no limit.
153
+ # Agent max spend dollars one SDK run may spend (`maxBudgetUsd`); the run
154
+ # then ends `spend-limit`. `$` and `USD` read, e.g. `$20`.
155
+ # Slice max spend dollars one slice's runs may total, read from the slice-
156
+ # spend record before each run. Both: absent/blank = no
157
+ # limit; present and unreadable (0, negative, text) refuses
158
+ # the worker's start.
157
159
  # Plot 2 posture keys (repo-declared ceremony bounds; all optional):
158
160
  # Plan PRs required | never | optional (never = hard gate)
159
161
  # Implementation home this repo | <repo/path list> | none
@@ -191,6 +193,14 @@
191
193
  # CI jenkins | github-actions | none — which CI system this
192
194
  # project uses. Recorded by /plot-board-setup; not yet
193
195
  # read by the board.
196
+ # Default branch checks
197
+ # comma-separated workflow names whose runs decide whether
198
+ # the default branch is red (`CI, Lint`). Read by fleetd
199
+ # where it writes `.plot/state/default-branch.json`; a run
200
+ # of any other workflow is not folded, so a publishing or
201
+ # release workflow cannot raise the `default-branch-red`
202
+ # hold or the board's red-branch status. Names match a run's
203
+ # workflow name exactly. Absent = every workflow's runs.
194
204
  # Jenkins instance the slug or URL passed to a Jenkins CLI's -I flag.
195
205
  # Read back by /plot-board-setup to verify auth against
196
206
  # the right instance — without it the only runnable
@@ -29,19 +29,12 @@
29
29
  # now points at, so a second occurrence is visible in a log rather than
30
30
  # invisible in a working system.
31
31
  #
32
- # IT DOES NOT REPAIR A SYMREF THAT RESOLVES. Only an unresolvable one is broken.
33
- # A clone whose `origin/HEAD` deliberately names a non-default branch is
34
- # somebody's choice, and `--auto` would silently overrule it.
35
- #
36
- # WHAT LEAVES THE PIN BEHIND IS NOT REPAIRED HERE, and the leave-alone rule is
37
- # what keeps this safe alongside it. `packages/domain/corpus/refs.corpus.test.ts`
38
- # repoints `origin/HEAD` at a `plot-corpus-pin` ref it creates in `beforeAll`
39
- # and restores in `afterAll` — deliberately, so two readings of the estate see
40
- # one world. While that suite runs the pin RESOLVES, so this repairs nothing and
41
- # the suite is unaffected. What was measured on 2026-09-04 is the state after a
42
- # run that never reached its `afterAll`: the symref left behind, the ref it
43
- # names gone. Fixing that belongs to the suite; this repairs the symptom and
44
- # reports it loudly enough that the cause stays findable.
32
+ # IT REPAIRS A SYMREF THAT RESOLVES ONLY WHEN IT NAMES `plot-corpus-pin`. A
33
+ # clone whose `origin/HEAD` deliberately names another non-default branch is
34
+ # somebody's choice, and `--auto` would silently overrule it. No operator
35
+ # chooses the pin: `packages/domain/corpus/refs.corpus.test.ts` pins its own
36
+ # disposable clone, so a symref naming it in any other repository is the
37
+ # leftover of an interrupted run.
45
38
 
46
39
  # Whether `refs/remotes/origin/HEAD` names a ref that exists.
47
40
  #
@@ -51,14 +44,17 @@
51
44
  # Usage: origin_head_resolves [<repo-dir>]
52
45
  # Returns: 0 when it resolves — including when there is no symref at all, which
53
46
  # is a FRESH CLONE rather than a corruption and has nothing to repair.
47
+ # A symref naming `plot-corpus-pin` is corrupt even when it resolves:
48
+ # that name is left behind only by an interrupted corpus run, never by
49
+ # a live one, since the corpus pins its own clone.
54
50
  origin_head_resolves() {
55
51
  local dir="${1:-.}" target
56
52
  target=$(git -C "$dir" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null) || return 0
57
- [ -n "$target" ] || return 0
53
+ case "$target" in '') return 0 ;; refs/remotes/origin/plot-corpus-pin) return 1 ;; esac
58
54
  git -C "$dir" rev-parse --verify --quiet "${target}^{commit}" >/dev/null 2>&1
59
55
  }
60
56
 
61
- # Repairs an unresolvable `refs/remotes/origin/HEAD`, and says what it did.
57
+ # Repairs a `refs/remotes/origin/HEAD` that `origin_head_resolves` refuses, and says what it did.
62
58
  #
63
59
  # The repair is `git remote set-head origin --auto`, which asks the remote. It
64
60
  # is cheap — measured under a second — and it is the same command that fixed
@@ -70,16 +66,16 @@ origin_head_resolves() {
70
66
  # this is a self-heal on a path that has its own refusal downstream,
71
67
  # so it must never become a second way to stop.
72
68
  repair_origin_head() {
73
- local dir="${1:-.}" was now
69
+ local dir="${1:-.}" was why
74
70
  origin_head_resolves "$dir" && return 0
75
71
 
76
72
  was=$(git -C "$dir" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)
73
+ why="does not resolve"; [ "$was" != origin/plot-corpus-pin ] || why="is the corpus pin, left by an interrupted corpus run"
77
74
  if ! git -C "$dir" remote set-head origin --auto >/dev/null 2>&1; then
78
- echo "plot: origin/HEAD points at '$was', which does not resolve, and 'git remote set-head origin --auto' failed — the remote could not be asked." >&2
75
+ echo "plot: origin/HEAD points at '$was', which $why, and 'git remote set-head origin --auto' failed — the remote could not be asked." >&2
79
76
  return 0
80
77
  fi
81
- now=$(git -C "$dir" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)
82
- echo "plot: repaired origin/HEAD — it pointed at '$was', which does not exist on the remote; it now points at '${now:-<unset>}'." >&2
78
+ echo "plot: repaired origin/HEAD — it pointed at '$was', which $why; it now points at '$(git -C "$dir" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || echo '<unset>')'." >&2
83
79
  return 0
84
80
  }
85
81
 
@@ -220,7 +220,7 @@
220
220
  # every run.
221
221
  #
222
222
  # 2. `.plot/state/last-pulse.json` — the bridge, written by `write_bridge` on
223
- # the success path of `--stream` (what the board spawns) and `--log-pulse`
223
+ # the success path of `--stream` (unless PLOT_SCAN_RECORD=0) and `--log-pulse`
224
224
  # (what /plot-pulse passes). Those are the two callers that produce a pulse
225
225
  # for somebody to READ; plain `--json` is a query and records nothing. That
226
226
  # is a CACHE WITH AN EXPIRY: `pulse-bridge.ts` discards it after 15 minutes
@@ -311,7 +311,7 @@ while [ $# -gt 0 ]; do
311
311
  # caught this: `conflicts: the scan writes NOTHING` and `fleet: scan is
312
312
  # read-only`, both of which drive `--json`.
313
313
  --json) as_json=1; build_doc=1 ;;
314
- --stream) as_json=1; stream=1; build_doc=1; record=1 ;;
314
+ --stream) as_json=1; stream=1; build_doc=1; [ "${PLOT_SCAN_RECORD:-1}" = 0 ] || record=1 ;;
315
315
  -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
316
316
  *) slug="$1" ;;
317
317
  esac
package/plot-host.sh CHANGED
@@ -66,9 +66,17 @@
66
66
  # EXIT 3 is the question failing, and it is not
67
67
  # the same as an empty answer: a diff that could
68
68
  # not be read is not a diff that was empty.
69
+ # pr-merged-heads <branch> the head commit of every MERGED PR for this
70
+ # branch, one sha per line, or EMPTY (exit 0)
71
+ # where none merged. Reads `mergedAt`, never
72
+ # `state`. EXIT 3 is the question failing,
73
+ # including a CLI that fails without a word: an
74
+ # empty answer sends the reaper to a weaker
75
+ # reading, so only a recognised lookup miss is
76
+ # empty.
69
77
  # pr-create --title T [--body B] [--base BR] [--head BR] [--draft]
70
78
  # create a PR, print its URL
71
- # pr-merge <number> [--squash] [--delete-branch]
79
+ # pr-merge <number> [--squash] [--delete-branch] [--match-head <sha>]
72
80
  # pr-ready <number> take a PR out of draft
73
81
  # merge the PR
74
82
  # pr-list [--state open|merged|closed|all] [--limit N] [--rich|--rich-open]
@@ -448,6 +456,17 @@ die() { echo "plot-host: $*" >&2; exit 1; }
448
456
  # error a person must fix, not a transient the board should retry past.
449
457
  die3() { echo "plot-host: $*" >&2; exit 3; }
450
458
 
459
+ # THE ONE FOLD of a PR's check rollup into a word. `pr-list` and `pr-state` both
460
+ # read it, so what `green` means cannot differ between a listing and a merge.
461
+ # An allow-list: `ck` reads `ok` only for a finished item with an accepted
462
+ # result, `wait` for an unfinished one, and `bad` for every other word.
463
+ CHECKS_OF='def ck: (.conclusion // "") as $k | (.status // "") as $s | (if $s != "" then $s else (.state // "") end) as $w |
464
+ if $k != "" and ($s|IN("","COMPLETED")) then (if ($k|IN("SUCCESS","NEUTRAL","SKIPPED")) then "ok" else "bad" end)
465
+ elif ($w|IN("","QUEUED","IN_PROGRESS","WAITING","REQUESTED","PENDING","EXPECTED")) then "wait"
466
+ elif $s == "" and $w == "SUCCESS" then "ok" else "bad" end;
467
+ def checks_of: if (.statusCheckRollup|length) == 0 then "none" elif any(.statusCheckRollup[]; ck == "bad") then "failing"
468
+ elif any(.statusCheckRollup[]; ck == "wait") then "pending" else "green" end;'
469
+
451
470
  # Exit 5 — the host refused to answer FOR NOW. A rate limit, primary or
452
471
  # secondary: nothing is broken, nothing needs fixing, and the same question
453
472
  # asked later will be answered.
@@ -1657,6 +1676,74 @@ jenkins_job_url_path() { # $1 = job path, $2 = branch or ""
1657
1676
  printf '%s' "$out"
1658
1677
  }
1659
1678
 
1679
+ # Every Jenkins build of one job that built ONE sha, as a JSON array (newest
1680
+ # first), or exit 3 (no instance) / exit 4 (cannot be asked). Shared by
1681
+ # `run-for-sha` and `runs-for-sha`, so the instance, the credential and the
1682
+ # multibranch-then-plain URL fallback are written once.
1683
+ #
1684
+ # $1 = the op's name, $2 = branch, $3 = how many builds to list, $4 = the sha.
1685
+ # Run it in `$(...)` and read the exit code with `|| exit $?`: it exits rather
1686
+ # than returns, and a subshell's exit is the code the caller sees.
1687
+ #
1688
+ # THE SHA IS IN JENKINS AND `jen` IS NOT THE TRANSPORT. Measured 2026-09-10: a
1689
+ # `jen build list --json` entry carries no sha, so Jenkins' REST API answers it
1690
+ # at `actions[].lastBuiltRevision.SHA1`. One `tree=` query returns a whole
1691
+ # history, so this costs one round trip like the GitHub arm.
1692
+ #
1693
+ # A BRANCH IS A JOB SEGMENT ON A MULTIBRANCH JOB AND NOT ON A PLAIN ONE, and no
1694
+ # reading of the configured path says which this is. The multibranch URL is
1695
+ # tried first and the plain one is the fallback (measured 2026-09-11: asking
1696
+ # the plain job for a branch segment answers 404). THE PLAIN JOB REPORTS ITS
1697
+ # OWN BUILDS whatever branch was asked about; the `sha` says which it built.
1698
+ #
1699
+ # NO CREDENTIAL IS *CANNOT BE ASKED*, never *no run*: the keychain is macOS-only
1700
+ # and a Linux agent legitimately has none. AN UNREACHABLE INSTANCE IS NOT AN
1701
+ # EMPTY HISTORY: a refused or redirected request answers HTML, which fails the
1702
+ # `builds` test.
1703
+ #
1704
+ # ONLY THE ASKED-FOR SHA, never another build's. `result` is null while a build
1705
+ # runs, Jenkins' own word for *in flight*, mapped to the `status`/`conclusion`
1706
+ # split the contract already uses so the shape does not fork per connector.
1707
+ jenkins_sha_runs() {
1708
+ local op="$1" branch="$2" limit="$3" sha="$4" instance host job cred tree body try path
1709
+ instance="$(jenkins_instance)"
1710
+ [ -n "$instance" ] || jenkins_no_instance
1711
+ host="${instance%%/*}"
1712
+ job="${instance#*/}"
1713
+ [ "$job" = "$instance" ] && job=""
1714
+ [ -n "${PLOT_JENKINS_JOB:-}" ] && job="$PLOT_JENKINS_JOB"
1715
+ if [ -z "$job" ]; then
1716
+ echo "plot-host: $op — the Jenkins instance names no job path; a sha lives in a job's builds, so it must be <slug>/<job/path>, not a bare host" >&2
1717
+ exit 4
1718
+ fi
1719
+ cred="$(jenkins_rest_credential "$host")" || {
1720
+ echo "plot-host: $op — no Jenkins API credential for '$host'" >&2
1721
+ echo " Jenkins' REST API takes basic auth with an API token, which \`jen auth login\` stores in the login keychain. The Keycloak bearer from \`jen auth token\` is NOT it." >&2
1722
+ exit 4
1723
+ }
1724
+ tree="tree=builds%5Bnumber,result,building,timestamp,url,actions%5BlastBuiltRevision%5BSHA1%5D%5D%5D%7B0,$limit%7D"
1725
+ body=""
1726
+ for path in "$(jenkins_job_url_path "$job" "$branch")" "$(jenkins_job_url_path "$job" "")"; do
1727
+ host_slot_take jenkins ''
1728
+ try=$(curl -sg --max-time 30 -u "$cred" "https://$host$path/api/json?$tree" 2>/dev/null) || true
1729
+ host_slot_give; budget_record_call jenkins ''
1730
+ if printf '%s' "$try" | jq -e 'has("builds")' >/dev/null 2>&1; then body="$try"; break; fi
1731
+ done
1732
+ cred=""
1733
+ if [ -z "$body" ]; then
1734
+ echo "plot-host: $op — Jenkins did not answer for '$host'" >&2
1735
+ exit 4
1736
+ fi
1737
+ printf '%s' "$body" | jq -c --arg sha "$sha" '
1738
+ [ .builds[]
1739
+ | { sha: ([ .actions[]? | select(.lastBuiltRevision) | .lastBuiltRevision.SHA1 ] | first // ""),
1740
+ status: (if .building then "in_progress" else "completed" end),
1741
+ conclusion: (if .building then null else (.result // null) end),
1742
+ url: (.url // ""),
1743
+ startedAt: (if .timestamp then (.timestamp / 1000 | todate) else "" end) } ]
1744
+ | map(select(.sha == $sha))' || exit 4
1745
+ }
1746
+
1660
1747
  ci_unaskable() { # $1 = the op's name, $2 = the CI word (may be empty)
1661
1748
  local ci_word="${2:-}"
1662
1749
  if [ -z "$ci_word" ] || [ "$ci_word" = none ]; then
@@ -1993,7 +2080,7 @@ rest_pr_to_state() {
1993
2080
  state: $state,
1994
2081
  draft: (.draft // false),
1995
2082
  url: (.html_url // ""),
1996
- mergeCommit: (.merge_commit_sha // "") }
2083
+ mergeCommit: (.merge_commit_sha // ""), headSha: (.head.sha // ""), checks: "unknown" }
1997
2084
  '
1998
2085
  }
1999
2086
 
@@ -3485,9 +3572,9 @@ case "$op" in
3485
3572
  # mergeCommit is what lets a caller ask "which release contains this?" —
3486
3573
  # `git tag --contains <sha>` answers exactly, where dates cannot. It is ""
3487
3574
  # for anything unmerged, which is the honest answer rather than a guess.
3488
- elif out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr view "$ref" --json number,state,isDraft,url,mergeCommit 2>"$HOST_ERR")"; then
3575
+ elif out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr view "$ref" --json number,state,isDraft,url,mergeCommit,headRefOid,statusCheckRollup 2>"$HOST_ERR")"; then
3489
3576
  rm -f "$HOST_ERR"
3490
- jq -c '{number:.number,state:.state,draft:.isDraft,url:.url,mergeCommit:(.mergeCommit.oid // "")}' <<<"$out"
3577
+ jq -c "$CHECKS_OF"'{number:.number,state:.state,draft:.isDraft,url:.url,mergeCommit:(.mergeCommit.oid // ""),headSha:(.headRefOid // ""),checks:checks_of,checksSha:(.headRefOid // "")}' <<<"$out"
3491
3578
  else
3492
3579
  err="$(cat "$HOST_ERR" 2>/dev/null)"; rm -f "$HOST_ERR"
3493
3580
  # REFUSED FOR RATE IS NOT ANSWERED. The budget gate above could not see
@@ -3605,7 +3692,8 @@ case "$op" in
3605
3692
  *) die "pr-merged: unknown arg $1" ;;
3606
3693
  esac
3607
3694
  done
3608
- if [ "$be" = "github" ]; then
3695
+ # NO REMOTE, NO PR: no repository holds one, so nothing merged, whatever gh's auth says.
3696
+ if [ ${#repo_args[@]} -eq 0 ] && [ -z "$(git remote 2>/dev/null)" ]; then echo "not-merged"; elif [ "$be" = "github" ]; then
3609
3697
  # --state all, because a merged PR reports CLOSED and the default `open`
3610
3698
  # would hide every one of them. --limit 100 rather than 1: the newest PR
3611
3699
  # is not the merge, exactly as the state is not the merge.
@@ -3722,6 +3810,56 @@ case "$op" in
3722
3810
  fi
3723
3811
  ;;
3724
3812
 
3813
+ pr-merged-heads)
3814
+ # THE HEAD COMMIT OF EVERY MERGED PR FOR A BRANCH, one sha per line.
3815
+ # `plot-reap.mjs` asks it only for a branch already known merged, to tell a
3816
+ # pushed commit from one made after the merge once the remote ref is gone.
3817
+ #
3818
+ # `--state all` and `--limit 100` for `pr-merged`'s own two reasons: a
3819
+ # merged PR reports CLOSED, and the newest PR is not the merge.
3820
+ #
3821
+ # A FAILURE WITH NO MESSAGE IS A FAILURE HERE, unlike `pr-state`: an empty
3822
+ # answer makes the caller fall back to a patch-id reading, so silence must
3823
+ # not stand in for *no merged head*. Only a recognised lookup miss is empty.
3824
+ ref="${1:?pr-merged-heads needs a branch}"; shift || true
3825
+ repo_args=()
3826
+ while [ $# -gt 0 ]; do
3827
+ case "$1" in
3828
+ --repo) repo_args=(-R "${2:?}"); shift 2 ;;
3829
+ *) die "pr-merged-heads: unknown arg $1" ;;
3830
+ esac
3831
+ done
3832
+ if [ "$be" = "github" ]; then
3833
+ if out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr list --head "$ref" --state all --limit 100 --json mergedAt,headRefOid 2>"$HOST_ERR")"; then
3834
+ rm -f "$HOST_ERR"
3835
+ jq -r '.[] | select(.mergedAt != null and .headRefOid != null) | .headRefOid' <<<"$out" || exit 3
3836
+ else
3837
+ err="$(cat "$HOST_ERR" 2>/dev/null)"; rm -f "$HOST_ERR"
3838
+ if [ -n "$err" ] && is_lookup_miss "$err"; then
3839
+ :
3840
+ else
3841
+ echo "plot-host: ${err:-gh pr list failed}" >&2
3842
+ exit 3
3843
+ fi
3844
+ fi
3845
+ else
3846
+ bb_require_json
3847
+ # Bitbucket names the merged head `source.commit.hash`.
3848
+ if out="$(bb ${repo_args[@]+"${repo_args[@]}"} pr list --state merged --json 2>"$HOST_ERR")"; then
3849
+ rm -f "$HOST_ERR"
3850
+ jq -r --arg b "$ref" '.[] | select(.source.branch.name==$b) | (.source.commit.hash // empty)' <<<"$out" || exit 3
3851
+ else
3852
+ err="$(cat "$HOST_ERR" 2>/dev/null)"; rm -f "$HOST_ERR"
3853
+ if [ -n "$err" ] && is_lookup_miss "$err"; then
3854
+ :
3855
+ else
3856
+ echo "plot-host: ${err:-bb pr list failed}" >&2
3857
+ exit 3
3858
+ fi
3859
+ fi
3860
+ fi
3861
+ ;;
3862
+
3725
3863
  pr-create)
3726
3864
  title=""; body=""; base=""; head=""; draft=0
3727
3865
  while [ $# -gt 0 ]; do
@@ -3752,11 +3890,12 @@ case "$op" in
3752
3890
 
3753
3891
  pr-merge)
3754
3892
  num="${1:?pr-merge needs a PR number}"; shift
3755
- squash=0; delbranch=0
3893
+ squash=0; delbranch=0; pin=""
3756
3894
  while [ $# -gt 0 ]; do
3757
3895
  case "$1" in
3758
3896
  --squash) squash=1; shift ;;
3759
3897
  --delete-branch) delbranch=1; shift ;;
3898
+ --match-head) pin="${2:?pr-merge --match-head needs a commit}"; shift 2 ;;
3760
3899
  *) die "pr-merge: unknown arg $1" ;;
3761
3900
  esac
3762
3901
  done
@@ -3764,7 +3903,9 @@ case "$op" in
3764
3903
  args=(pr merge "$num")
3765
3904
  [ "$squash" = 1 ] && args+=(--squash) || args+=(--merge)
3766
3905
  [ "$delbranch" = 1 ] && args+=(--delete-branch)
3906
+ [ -n "$pin" ] && args+=(--match-head-commit "$pin")
3767
3907
  gh "${args[@]}"
3908
+ elif [ -n "$pin" ]; then echo "plot-host: pr-merge --match-head: bitbucket cannot pin a merge to a commit; nothing was merged" >&2; exit 4
3768
3909
  else
3769
3910
  args=(pr merge "$num")
3770
3911
  [ "$squash" = 1 ] && args+=(--squash)
@@ -4034,6 +4175,11 @@ case "$op" in
4034
4175
  # GitHub's statusCheckRollup. Done-when 3 verifies this is orthogonal:
4035
4176
  # a GitHub repo without Jenkins still reads its own rollup exactly as
4036
4177
  # before.
4178
+ # COMMIT FIELDS PER ARM. `headSha` is `headRefOid` on all three GitHub
4179
+ # arms. `checksSha` is emitted ONLY by the rollup arm: `statusCheckRollup`
4180
+ # belongs to the head commit, so it equals `headSha`. The Jenkins colours
4181
+ # are per branch and carry no commit, and the plain arm reads no checks,
4182
+ # so neither emits `checksSha`. `mergedAt` is the host's, `""` on an open PR.
4037
4183
  if [ "$ci" = "jenkins" ]; then
4038
4184
  # GitHub PR list, but `checks` comes from Jenkins, joined on branch
4039
4185
  # name. `statusCheckRollup` is NOT even requested — the GitHub rollup
@@ -4043,7 +4189,7 @@ case "$op" in
4043
4189
  # $jentry == null → the branch has no Jenkins job; `none`.
4044
4190
  # otherwise → the joined colour's `checks`, job named on fail.
4045
4191
  _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
4046
- --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author)" || exit $?
4192
+ --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4047
4193
  pr_list_report_truncation github "$limit" "$state" \
4048
4194
  "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4049
4195
  printf '%s' "$_gh_raw" \
@@ -4063,7 +4209,7 @@ case "$op" in
4063
4209
  else "unknown" end),
4064
4210
  review:(.reviewDecision // ""),
4065
4211
  url:.url,
4066
- updatedAt:(.updatedAt // ""),
4212
+ updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),
4067
4213
  author:(.author.login // ""),
4068
4214
  failing_checks:(
4069
4215
  if $jentry != null and $jentry.checks == "failing"
@@ -4074,35 +4220,24 @@ case "$op" in
4074
4220
  else
4075
4221
  # GitHub without Jenkins (or Jenkins not configured): use GitHub rollup
4076
4222
  _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
4077
- --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author)" || exit $?
4223
+ --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4078
4224
  pr_list_report_truncation github "$limit" "$state" \
4079
4225
  "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4080
4226
  printf '%s' "$_gh_raw" \
4081
- | jq -c '.[] | {
4227
+ | jq -c "$CHECKS_OF"'.[] | {
4082
4228
  number:.number, title:.title, state:.state, head:.headRefName,
4083
4229
  draft:.isDraft,
4084
- checks:(
4085
- if (.statusCheckRollup|length) == 0 then "none"
4086
- elif any(.statusCheckRollup[]; (if (.conclusion // "") != "" then .conclusion else (.status // .state) end) as $c
4087
- | $c=="FAILURE" or $c=="ERROR" or $c=="CANCELLED"
4088
- or $c=="TIMED_OUT" or $c=="ACTION_REQUIRED") then "failing"
4089
- elif any(.statusCheckRollup[]; (if (.conclusion // "") != "" then .conclusion else (.status // .state) end) as $c
4090
- | $c=="PENDING" or $c=="IN_PROGRESS" or $c=="QUEUED"
4091
- or $c=="WAITING" or $c==null) then "pending"
4092
- else "green" end),
4230
+ checks:checks_of,
4093
4231
  mergeable:(
4094
4232
  if .mergeable=="CONFLICTING" or .mergeStateStatus=="DIRTY" then "conflicting"
4095
4233
  elif .mergeable=="MERGEABLE" then "mergeable"
4096
4234
  else "unknown" end),
4097
4235
  review:(.reviewDecision // ""),
4098
4236
  url:.url,
4099
- updatedAt:(.updatedAt // ""),
4237
+ updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),checksSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),
4100
4238
  author:(.author.login // ""),
4101
4239
  failing_checks:[
4102
- .statusCheckRollup[]? | select((if (.conclusion // "") != "" then .conclusion else (.status // .state) end) as $c
4103
- | $c=="FAILURE" or $c=="ERROR" or $c=="CANCELLED"
4104
- or $c=="TIMED_OUT" or $c=="ACTION_REQUIRED")
4105
- | (.name // .context // "")] | map(select(. != ""))
4240
+ .statusCheckRollup[]? | select(ck == "bad") | (.name // .context // "")] | map(select(. != ""))
4106
4241
  }'
4107
4242
  fi
4108
4243
  else
@@ -4120,13 +4255,17 @@ case "$op" in
4120
4255
  # the store unable to narrow and the daily full read would never fall
4121
4256
  # due against anything but a cold window.
4122
4257
  _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
4123
- --json number,title,state,headRefName,isDraft,url,updatedAt,author)" || exit $?
4258
+ --json number,title,state,headRefName,isDraft,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4124
4259
  pr_list_report_truncation github "$limit" "$state" \
4125
4260
  "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4126
4261
  printf '%s' "$_gh_raw" \
4127
- | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),author:(.author.login // "")}'
4262
+ | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),author:(.author.login // "")}'
4128
4263
  fi
4129
4264
  else
4265
+ # `headSha` IS `.source.commit.hash`, which the pullrequests endpoint
4266
+ # carries. The endpoint has no `merged_on`, so `mergedAt` is `.updated_on`
4267
+ # of a MERGED PR only; `checksSha` is absent, as `bb` reads no checks.
4268
+ #
4130
4269
  # `author` IS THE `nickname`, the one handle field a Bitbucket user
4131
4270
  # object carries. Measured 2026-09-25 against bb 1.9.0: `author` holds
4132
4271
  # `display_name`, `nickname`, `account_id` and `uuid` and no username,
@@ -4219,7 +4358,7 @@ case "$op" in
4219
4358
  mergeable:"unknown",
4220
4359
  review:"",
4221
4360
  url:(.links.html.href // ""),
4222
- updatedAt:(.updated_on // ""),
4361
+ updatedAt:(.updated_on // ""),headSha:(.source.commit.hash // ""),mergedAt:(if .state=="MERGED" then (.updated_on // "") else "" end),
4223
4362
  author:(.author.nickname // ""),
4224
4363
  failing_checks:(
4225
4364
  if $jentry != null and $jentry.checks == "failing"
@@ -4231,7 +4370,7 @@ case "$op" in
4231
4370
  # Bitbucket without Jenkins: checks remain unknown
4232
4371
  PR_LIST_JQ_ARGS=()
4233
4372
  pr_list_states bitbucket "$limit" "$bb_states" \
4234
- '.[] | {number:.id,title:.title,state:(if .state=="DECLINED" then "CLOSED" else .state end),head:.source.branch.name,draft:(.draft // false),checks:"unknown",mergeable:"unknown",review:"",url:(.links.html.href // ""),updatedAt:(.updated_on // ""),author:(.author.nickname // ""),failing_checks:[]}' \
4373
+ '.[] | {number:.id,title:.title,state:(if .state=="DECLINED" then "CLOSED" else .state end),head:.source.branch.name,draft:(.draft // false),checks:"unknown",mergeable:"unknown",review:"",url:(.links.html.href // ""),updatedAt:(.updated_on // ""),headSha:(.source.commit.hash // ""),mergedAt:(if .state=="MERGED" then (.updated_on // "") else "" end),author:(.author.nickname // ""),failing_checks:[]}' \
4235
4374
  "${bb_cmd[@]}" || exit $?
4236
4375
  fi
4237
4376
  else
@@ -4334,8 +4473,16 @@ case "$op" in
4334
4473
  esac
4335
4474
  ;;
4336
4475
 
4337
- run-for-sha)
4338
- # The run for ONE sha, or nothing — the BuildMonitor's only host question.
4476
+ run-for-sha|runs-for-sha)
4477
+ # `runs-for-sha` is this op's plural: EVERY run for the sha as a JSON array
4478
+ # (`[]` is an answer, exit 4 is *cannot be asked*), from ONE listing call and
4479
+ # no per-run `gh run view`. The default branch needs it because `main` runs
4480
+ # several workflows per commit and the first match alone would let a green
4481
+ # first run hide a red second one. Facts only: `status` and `conclusion` as
4482
+ # the host gives them, Jenkins' words included.
4483
+ #
4484
+ # The singular, below, is the BuildMonitor's only host question.
4485
+ #
4339
4486
  #
4340
4487
  # WHY THIS IS NOT `runs`. `runs` is branch-scoped and reports no sha at all,
4341
4488
  # so a caller cannot tell which commit an answer is about. `gh run list
@@ -4365,8 +4512,8 @@ case "$op" in
4365
4512
  # A Bitbucket remote exits 4 (`bb` has no run listing), as does a failing
4366
4513
  # `gh` or Jenkins that cannot be asked: exit 4 reads as unavailable, never
4367
4514
  # as "this sha has no build".
4368
- branch="${1:?run-for-sha needs a branch}"; shift
4369
- sha="${1:?run-for-sha needs a sha}"; shift
4515
+ branch="${1:?$op needs a branch}"; shift
4516
+ sha="${1:?$op needs a sha}"; shift
4370
4517
  # Enough runs to find the sha among its neighbours. A branch accumulates
4371
4518
  # runs per push and per workflow, so the sha being asked about can sit
4372
4519
  # several entries down even when it is the current head.
@@ -4374,7 +4521,7 @@ case "$op" in
4374
4521
  while [ $# -gt 0 ]; do
4375
4522
  case "$1" in
4376
4523
  --limit) limit="${2:?}"; shift 2 ;;
4377
- *) die "run-for-sha: unknown arg $1" ;;
4524
+ *) die "$op: unknown arg $1" ;;
4378
4525
  esac
4379
4526
  done
4380
4527
  # DISPATCHED ON THE CI SYSTEM, for the reason `runs` above states: the git
@@ -4395,80 +4542,11 @@ case "$op" in
4395
4542
  #
4396
4543
  # THIS ARM EXITED 4 UNTIL 2026-09-11, and the refusal was honest for
4397
4544
  # the transport it had. What changed is the transport, not the rule.
4398
- _jen_instance="$(jenkins_instance)"
4399
- [ -n "$_jen_instance" ] || jenkins_no_instance
4400
- _jen_host="${_jen_instance%%/*}"
4401
- _jen_job="${_jen_instance#*/}"
4402
- [ "$_jen_job" = "$_jen_instance" ] && _jen_job=""
4403
- [ -n "${PLOT_JENKINS_JOB:-}" ] && _jen_job="$PLOT_JENKINS_JOB"
4404
- if [ -z "$_jen_job" ]; then
4405
- # A bare-host instance names no job, and a sha lives in a job's
4406
- # builds. `runs` degrades to an empty map here; this op has no row to
4407
- # carry that, so the only way to say *cannot be asked* is exit 4.
4408
- echo "plot-host: run-for-sha — the Jenkins instance names no job path" >&2
4409
- echo " A sha is a fact about a job's builds, so the instance must be" >&2
4410
- echo " <slug>/<job/path> rather than a bare host." >&2
4411
- exit 4
4412
- fi
4413
- _jen_cred="$(jenkins_rest_credential "$_jen_host")" || {
4414
- # NO CREDENTIAL IS *CANNOT BE ASKED*, never *no run*. The keychain is
4415
- # macOS-only and a Linux agent legitimately has none; saying nothing
4416
- # at exit 0 would read as a branch that never built.
4417
- echo "plot-host: run-for-sha — no Jenkins API credential for '$_jen_host'" >&2
4418
- echo " Jenkins' REST API takes basic auth with an API token, which" >&2
4419
- echo " \`jen auth login\` stores in the login keychain. The Keycloak" >&2
4420
- echo " bearer from \`jen auth token\` is NOT it — Jenkins answers that" >&2
4421
- echo " with a login redirect." >&2
4422
- exit 4
4423
- }
4424
- # A BRANCH IS A JOB SEGMENT ON A MULTIBRANCH JOB AND NOT ON A PLAIN
4425
- # ONE, and no reading of the configured path says which this is. So the
4426
- # multibranch URL is tried first and the plain one is the fallback:
4427
- # `job/quaweb/job/continuous-build/job/content%2Fctas` against
4428
- # `job/quaweb/job/release`. Measured 2026-09-11 — asking the plain job
4429
- # for a branch segment answers 404, which is why guessing one shape
4430
- # cost a run.
4431
- #
4432
- # THE PLAIN JOB REPORTS ITS OWN BUILDS whatever branch was asked about,
4433
- # and that is honest rather than wrong: a pipeline job builds one
4434
- # thing, and the `sha` in the answer says which commit it built.
4435
- _jen_tree="tree=builds%5Bnumber,result,building,timestamp,url,actions%5BlastBuiltRevision%5BSHA1%5D%5D%5D%7B0,$limit%7D"
4436
- _jen_body=""
4437
- for _jen_path in \
4438
- "$(jenkins_job_url_path "$_jen_job" "$branch")" \
4439
- "$(jenkins_job_url_path "$_jen_job" "")"; do
4440
- host_slot_take jenkins ''
4441
- _jen_try=$(curl -sg --max-time 30 -u "$_jen_cred" \
4442
- "https://$_jen_host$_jen_path/api/json?$_jen_tree" 2>/dev/null) || true
4443
- host_slot_give
4444
- budget_record_call jenkins ''
4445
- if printf '%s' "$_jen_try" | jq -e 'has("builds")' >/dev/null 2>&1; then
4446
- _jen_body="$_jen_try"; break
4447
- fi
4448
- done
4449
- _jen_cred=""
4450
- if [ -z "$_jen_body" ] || ! printf '%s' "$_jen_body" | jq -e 'has("builds")' >/dev/null 2>&1; then
4451
- # AN UNREACHABLE INSTANCE IS NOT AN EMPTY HISTORY. A refused or
4452
- # redirected request answers HTML, which fails the `builds` test.
4453
- echo "plot-host: run-for-sha — Jenkins did not answer for '$_jen_host'" >&2
4454
- exit 4
4455
- fi
4456
- # THE SAME MATCH RULE AS THE GITHUB ARM: only the asked-for sha, never
4457
- # another build's. A build for any other commit is not evidence about
4458
- # this one, so no match means no output.
4459
- #
4460
- # `result` is null while a build runs, which is Jenkins' own word for
4461
- # *in flight* — mapped to the `status`/`conclusion` split the contract
4462
- # already uses, so the shape does not fork per connector.
4463
- printf '%s' "$_jen_body" | jq -c --arg sha "$sha" '
4464
- [ .builds[]
4465
- | { sha: ([ .actions[]? | select(.lastBuiltRevision) | .lastBuiltRevision.SHA1 ] | first // ""),
4466
- status: (if .building then "in_progress" else "completed" end),
4467
- conclusion: (if .building then null else (.result // null) end),
4468
- url: (.url // ""),
4469
- startedAt: (if .timestamp then (.timestamp / 1000 | todate) else "" end) } ]
4470
- | (map(select(.sha == $sha)) | .[0])
4471
- | select(. != null)' 2>/dev/null || true
4545
+ # The fetch, credential and match rule live in `jenkins_sha_runs`, which
4546
+ # `runs-for-sha` shares. `|| exit $?` keeps exit 3 (no instance) apart
4547
+ # from exit 4 (cannot be asked).
4548
+ _jen_all=$(jenkins_sha_runs "$op" "$branch" "$limit" "$sha") || exit $?
4549
+ if [ "$op" = runs-for-sha ]; then printf '%s' "$_jen_all"; else printf '%s' "$_jen_all" | jq -c '.[0] // empty' 2>/dev/null || true; fi
4472
4550
  # THIS ARM ANSWERS AND THE OP IS OVER. Everything below the `esac` is
4473
4551
  # the GitHub path — the old jenkins arm reached it only because it
4474
4552
  # ended in `exit 4`. Measured 2026-09-11: without this the answer was
@@ -4477,13 +4555,13 @@ case "$op" in
4477
4555
  exit 0
4478
4556
  ;;
4479
4557
  github-actions) : ;;
4480
- *) ci_unaskable run-for-sha "$_ci" ;;
4558
+ *) ci_unaskable "$op" "$_ci" ;;
4481
4559
  esac
4482
4560
  if [ "$be" != "github" ]; then
4483
4561
  # SAME SECOND CONDITION AS `runs`: `gh run list` reads the repository its
4484
4562
  # remote names, so `CI: github-actions` on a non-GitHub remote names runs
4485
4563
  # that cannot be reached from here.
4486
- echo "plot-host: run-for-sha — CI is github-actions but the git host is '$be'" >&2
4564
+ echo "plot-host: $op — CI is github-actions but the git host is '$be'" >&2
4487
4565
  echo " \`gh run list\` reads the runs of the repository its remote names," >&2
4488
4566
  echo " so there is no GitHub repository here to ask about." >&2
4489
4567
  exit 4
@@ -4508,13 +4586,32 @@ case "$op" in
4508
4586
  # a network failure exits 4 here, the way the Jenkins arm does, so the
4509
4587
  # monitor reads *could not ask* and not *no run yet*.
4510
4588
  _gh_runs=$(gh run list --branch "$branch" --limit "$limit" \
4511
- --json headSha,conclusion,status,startedAt,url 2>/dev/null) \
4512
- || { echo "plot-host: run-for-sha — gh run list failed for '$branch'" >&2; exit 4; }
4513
- printf '%s' "$_gh_runs" | jq -c --arg sha "$sha" \
4589
+ --json headSha,conclusion,status,startedAt,url,databaseId,workflowName 2>/dev/null) \
4590
+ || { echo "plot-host: $op — gh run list failed for '$branch'" >&2; exit 4; }
4591
+ if [ "$op" = runs-for-sha ]; then
4592
+ printf '%s' "$_gh_runs" | jq -c --arg sha "$sha" '[.[] | select(.headSha == $sha)
4593
+ | {sha:.headSha, workflow:(.workflowName // ""), status:.status,
4594
+ conclusion:(if (.conclusion // "") == "" then null else .conclusion end),
4595
+ url:.url, startedAt:.startedAt}]' || exit 4
4596
+ exit 0
4597
+ fi
4598
+ _gh_match=$(printf '%s' "$_gh_runs" | jq -c --arg sha "$sha" \
4514
4599
  '(map(select(.headSha == $sha)) | .[0]) | select(. != null)
4515
4600
  | {sha:.headSha, status:.status,
4516
4601
  conclusion:(if (.conclusion // "") == "" then null else .conclusion end),
4517
- url:.url, startedAt:.startedAt}' || exit 4
4602
+ url:.url, startedAt:.startedAt, databaseId:.databaseId}') || exit 4
4603
+ [ -n "$_gh_match" ] || exit 0
4604
+ # ONE MORE CALL, ONLY FOR A CONCLUDED FAILURE (#1295): `gh run view --json
4605
+ # jobs` is the only place a 0-step job (no runner ever picked up the run)
4606
+ # shows up, apart from a real failure. A run still going or that
4607
+ # succeeded costs no extra call.
4608
+ _gh_db_id=$(printf '%s' "$_gh_match" | jq -r 'if (.conclusion == "failure" or .conclusion == "cancelled") then .databaseId else "" end')
4609
+ _gh_match=$(printf '%s' "$_gh_match" | jq -c 'del(.databaseId)') || exit 4
4610
+ [ -z "$_gh_db_id" ] && { printf '%s' "$_gh_match"; exit 0; }
4611
+ # Slurped via stdin, never `--argjson`: that flag caps at 128 KB on Linux.
4612
+ _gh_jobs=$(gh run view "$_gh_db_id" --json jobs 2>/dev/null) || { echo "plot-host: run-for-sha — gh run view failed" >&2; exit 4; }
4613
+ jq -n -c --slurpfile match <(printf '%s' "$_gh_match") --slurpfile run <(printf '%s' "$_gh_jobs") \
4614
+ '$match[0] + {jobs: [$run[0].jobs[] | {conclusion, steps: (.steps | length)}]}' || exit 4
4518
4615
  ;;
4519
4616
 
4520
4617
  issue-list)