@plot-pm/board 0.27.0 → 0.28.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plot-pm/board",
3
- "version": "0.27.0",
3
+ "version": "0.28.0",
4
4
  "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
5
5
  "type": "module",
6
6
  "license": "CC0-1.0",
package/plot-config.sh CHANGED
@@ -240,7 +240,23 @@
240
240
  # of any other workflow is not folded, so a publishing or
241
241
  # release workflow cannot raise the `default-branch-red`
242
242
  # hold or the board's red-branch status. Names match a run's
243
- # workflow name exactly. Absent = every workflow's runs.
243
+ # workflow name exactly; a bare name folds the whole run.
244
+ # `<workflow>/<job>` (`CI/validate`) folds that one job of
245
+ # that workflow, under GitHub Actions only: a job name no
246
+ # job carries matches no run and reads `unknown`, never
247
+ # green. Absent = every workflow's runs.
248
+ # Merge checks comma-separated check names (a job's check run or a
249
+ # status context, `validate`) that `plot-ask.mjs merge`
250
+ # and fleetd's merge arm require to have a completed
251
+ # `success` on the pinned head. A named check with no run
252
+ # on the head, or a queued or running one, reads
253
+ # `pending` and refuses `checks-not-green`; of several
254
+ # completed runs of one name, the latest decides. Name the job
255
+ # that aggregates the selected jobs: a re-run removes a
256
+ # job from the rollup until it runs again, so the rest of
257
+ # the rollup can read green without it. Bitbucket reports
258
+ # no check runs, so a named check refuses there. Absent =
259
+ # no named check is required.
244
260
  # Jenkins instance the slug or URL passed to a Jenkins CLI's -I flag.
245
261
  # Read back by /plot-board-setup to verify auth against
246
262
  # the right instance — without it the only runnable
package/plot-host.sh CHANGED
@@ -531,21 +531,12 @@
531
531
  # The transition id is LOOKED UP, never guessed:
532
532
  # ids are per workflow and per issue, so a
533
533
  # hardcoded one writes to the wrong column.
534
- # pr-body <number> (--body B | --body-file F)
535
- # replace the PR description. GitHub replaces
534
+ # pr-body <number> [--body B | --body-file F]
535
+ # with no flag, print the PR description;
536
+ # with one, replace it. GitHub replaces
536
537
  # it over REST (`PATCH pulls/<n>`), which
537
538
  # spends `core` and never GraphQL. --body-file
538
539
  # reads the body from a file, on both ops.
539
- # rate-limit both GitHub budgets from `gh api rate_limit`.
540
- # SUPERSEDED BY `limit`, and kept only because
541
- # its callers have not moved: that endpoint was
542
- # measured 2026-09-01 reporting graphql
543
- # 5000/5000 used=0 while a real call's header
544
- # read Remaining 1236, Used 3764, and reproduced
545
- # 2026-09-02 against a header's 2732. NOTHING
546
- # ROUTES ON IT any more — `gh_route` reads the
547
- # budget record, which is written from response
548
- # headers. Prefer `limit`.
549
540
  # limit what is this connector's limit, and how well
550
541
  # does it know it? One JSON line per metered
551
542
  # bucket: {"connector","bucket","limit",
@@ -733,7 +724,9 @@ MERGEABLE_OF='def mergeable_of: if .mergeable == "CONFLICTING" or .mergeable ==
733
724
 
734
725
  # THE ONE PROJECTION of a GraphQL-shaped PR into `pr-state`'s printed line, read by
735
726
  # the GraphQL arm and by `rest_pr_state`, so the two transports print one shape.
736
- PR_STATE_OF='{number:.number,state:.state,draft:.isDraft,url:.url,mergeCommit:(.mergeCommit.oid // ""),head:(.headRefName // ""),headSha:(.headRefOid // ""),base:(.baseRefName // ""),checks:checks_of,ciChecks:ci_checks_of,checksSha:(.headRefOid // ""),mergeable:mergeable_of,mergedAt:(.mergedAt // "")}'
727
+ # `checkRuns` carries every rollup item unfolded, so the merge controller can
728
+ # require a named check (`Merge checks`) that the folded `checks` word cannot see.
729
+ PR_STATE_OF='{number:.number,state:.state,draft:.isDraft,url:.url,mergeCommit:(.mergeCommit.oid // ""),head:(.headRefName // ""),headSha:(.headRefOid // ""),base:(.baseRefName // ""),checks:checks_of,ciChecks:ci_checks_of,checkRuns:[.statusCheckRollup[]? | {name:(.name // .context // ""),status:(.status // .state // ""),conclusion:(.conclusion // ""),at:(.startedAt // "")}],checksSha:(.headRefOid // ""),mergeable:mergeable_of,mergedAt:(.mergedAt // "")}'
737
730
 
738
731
  # Exit 5 — the host refused to answer FOR NOW. A rate limit, primary or
739
732
  # secondary: nothing is broken, nothing needs fixing, and the same question
@@ -2447,14 +2440,19 @@ graphql_budget_spent() {
2447
2440
  #
2448
2441
  # THE ARMS, AND WHY EACH IS WHERE IT IS:
2449
2442
  #
2450
- # pr-state both transports. The only op with a REST fallback
2451
- # written, so the only one where the budget can change the
2452
- # answer.
2453
- # rate-limit|limit REST-only BY NATURE rather than by omission. Both are
2443
+ # pr-state both transports, so the budget can change the answer.
2444
+ # pr-list both transports for the PLAIN listing (`gh_pr_list_routed`).
2445
+ # `--rich`, `--rich-open`'s open half and the Jenkins arm stay
2446
+ # GraphQL whatever the route: REST's list endpoint carries no
2447
+ # check rollup, no `mergeable` and no `reviewDecision`, so a
2448
+ # rich row would cost four calls per PR on every refresh, and
2449
+ # `reviewDecision` has no REST field at all. A rich call with
2450
+ # GraphQL spent is refused (exit 5), never answered thinner.
2451
+ # limit REST-only BY NATURE rather than by omission. It is
2454
2452
  # reached through `gh api`, which is REST's transport.
2455
- # `limit` spends a GraphQL call to read its own headers —
2453
+ # It spends a GraphQL call to read its own headers —
2456
2454
  # the call it makes is GraphQL, the route to it is not.
2457
- # * GraphQL-only. Ten ops, and this is where "every op
2455
+ # * GraphQL-only. Nine ops, and this is where "every op
2458
2456
  # consults the router" is honest rather than decorative:
2459
2457
  # their answer is a statement about what THIS SCRIPT has
2460
2458
  # implemented, not about what GitHub offers, which serves
@@ -2467,8 +2465,9 @@ graphql_budget_spent() {
2467
2465
  # `PLOT_HOST_FORCE_REST=1` IS NOT A DEBUG SWITCH. It is how the rate-refusal
2468
2466
  # re-entry reaches the second path without a second copy of the REST code:
2469
2467
  # `pr-state` re-enters itself with the variable set after GraphQL is refused
2470
- # for rate. An operator may also set it, and that is supported, but the
2471
- # re-entry is why it exists. It is consulted before the budget because it is
2468
+ # for rate; plain `pr-list` asks REST in `gh_pr_list_routed` instead. An
2469
+ # operator may also set it, and that is supported, but the re-entry is why it
2470
+ # exists. It is consulted before the budget because it is
2472
2471
  # free and the budget read is not.
2473
2472
  #
2474
2473
  # THE BUDGET IS CONSULTED LAST, AND IT READS THE RECORD BY BUCKET NAME. Every
@@ -2488,11 +2487,11 @@ graphql_budget_spent() {
2488
2487
  gh_route() { # $1=op → graphql|rest
2489
2488
  case "${1:-}" in
2490
2489
  # REST-only: no GraphQL route exists to choose, so nothing is consulted.
2491
- rate-limit|limit|pr-create|pr-body)
2490
+ limit|pr-create|pr-body)
2492
2491
  printf 'rest\n'
2493
2492
  ;;
2494
- # Both transports implemented — the one op where the reasons apply.
2495
- pr-state)
2493
+ # Both transports implemented — the ops where the reasons apply.
2494
+ pr-state|pr-list)
2496
2495
  if [ "${PLOT_HOST_FORCE_REST:-0}" = "1" ] || graphql_budget_spent; then
2497
2496
  printf 'rest\n'
2498
2497
  else
@@ -2554,7 +2553,50 @@ rest_pr_state() { # $1=owner/repo $2=PR number or branch; returns 3 when the bra
2554
2553
  else pr="$(gh_api_harvest "repos/$1/pulls?head=${1%%/*}:$2&state=all&per_page=1")" || return 1; pr="$(jq -ce '.[0]' <<<"$pr")" || return 3; fi
2555
2554
  sha="$(jq -r '.head.sha // ""' <<<"$pr")"
2556
2555
  ck="$(gh_api_harvest "repos/$1/commits/$sha/check-runs?per_page=100")" && st="$(gh_api_harvest "repos/$1/commits/$sha/status?per_page=100")" || return 2
2557
- jq -cs "$CHECKS_OF$MERGEABLE_OF"'.[0] as $p | (.[1].check_runs // []) as $c | (.[2].statuses // []) as $s | (($p.merged == true) or ($p.merged_at != null)) as $m | {number: $p.number, state: (if $m then "MERGED" else ($p.state // "" | ascii_upcase) end), isDraft: ($p.draft // false), url: ($p.html_url // ""), mergeCommit: (if $m then {oid: ($p.merge_commit_sha // "")} else null end), headRefName: ($p.head.ref // ""), headRefOid: ($p.head.sha // ""), baseRefName: ($p.base.ref // ""), mergedAt: ($p.merged_at // ""), mergeable: (if $p.mergeable == true then "MERGEABLE" elif $p.mergeable == false then "CONFLICTING" else "UNKNOWN" end), mergeStateStatus: (($p.mergeable_state // "") | ascii_upcase), statusCheckRollup: ([$c[] | {name, status: ((.status // "") | ascii_upcase), conclusion: ((.conclusion // "") | ascii_upcase)}] + [$s[] | {context, state: ((.state // "") | ascii_upcase)}] + (if ((.[1].total_count // 0) > ($c | length)) or ((.[2].total_count // 0) > ($s | length)) then [{status: "QUEUED"}] else [] end))} |'"$PR_STATE_OF" <<<"$pr$ck$st"
2556
+ jq -cs "$CHECKS_OF$MERGEABLE_OF"'.[0] as $p | (.[1].check_runs // []) as $c | (.[2].statuses // []) as $s | (($p.merged == true) or ($p.merged_at != null)) as $m | {number: $p.number, state: (if $m then "MERGED" else ($p.state // "" | ascii_upcase) end), isDraft: ($p.draft // false), url: ($p.html_url // ""), mergeCommit: (if $m then {oid: ($p.merge_commit_sha // "")} else null end), headRefName: ($p.head.ref // ""), headRefOid: ($p.head.sha // ""), baseRefName: ($p.base.ref // ""), mergedAt: ($p.merged_at // ""), mergeable: (if $p.mergeable == true then "MERGEABLE" elif $p.mergeable == false then "CONFLICTING" else "UNKNOWN" end), mergeStateStatus: (($p.mergeable_state // "") | ascii_upcase), statusCheckRollup: ([$c[] | {name, status: ((.status // "") | ascii_upcase), conclusion: ((.conclusion // "") | ascii_upcase), startedAt: (.started_at // "")}] + [$s[] | {context, state: ((.state // "") | ascii_upcase), startedAt: (.created_at // "")}] + (if ((.[1].total_count // 0) > ($c | length)) or ((.[2].total_count // 0) > ($s | length)) then [{status: "QUEUED"}] else [] end))} |'"$PR_STATE_OF" <<<"$pr$ck$st"
2557
+ }
2558
+
2559
+ # GITHUB'S `pr-list`, ON THE ROUTE `gh_route` CHOSE. "$@" is the `gh pr list` argv,
2560
+ # asked while the route is `graphql` and always under `--rich`: REST's list has no
2561
+ # rollup, no `mergeable` and no `reviewDecision`, so a rich row has no REST form.
2562
+ # A plain call refused by GraphQL for rate asks REST once, as `pr-state` does; the
2563
+ # REST answer, or REST's own failure for `pr_list_call` to classify, is the op's. Measured 2026-11-16: GraphQL at 0
2564
+ # while REST answered, and every `pr-list` caller failed with exit 5.
2565
+ #
2566
+ # REST PRINTS THE ARRAY `gh` PRINTS for the plain fields (`number,title,state,
2567
+ # headRefName,baseRefName,isDraft,url,updatedAt,author,headRefOid,mergedAt`), so the plain
2568
+ # arm's one projection reads either. It reads the arm's `$state`, `$limit` (`gh`'s 30 when empty), `$since`
2569
+ # and one-branch `$head_args`. REST's `state` is `open|closed|all`: `merged` and
2570
+ # `closed` are its `closed` split on `merged_at`, as GraphQL splits them. Pages
2571
+ # run newest-created first, as `gh pr list` does; `--since` walks `sort=updated`
2572
+ # instead and stops at the first page that reaches the stamp. A failed page fails
2573
+ # the whole list, so no partial array is printed.
2574
+ gh_pr_list_routed() {
2575
+ local page=1 pages='' repo n="${limit:-30}" sel
2576
+ if [ "$route" != rest ] || [ "$rich" = 1 ]; then
2577
+ "$@" 2>"$HOST_ERR" && { cat "$HOST_ERR" >&2; return 0; }
2578
+ [ "$rich" = 0 ] && is_rate_refusal "$(cat "$HOST_ERR")" || { cat "$HOST_ERR" >&2; return 1; }
2579
+ fi
2580
+ repo="$(gh_rest_repo)"
2581
+ sel='def keep: .updated_at > $s and (if $st == "merged" then .merged_at != null elif $st == "closed" then .merged_at == null else true end);'
2582
+ while [ "$page" -gt 0 ]; do
2583
+ pages="$pages$(gh_api_harvest "repos/$repo/pulls?state=${state/merged/closed}&per_page=100&page=$page${since:+&sort=updated&direction=desc}${head_args[1]:+&head=${repo%%/*}:${head_args[1]}}")" || return
2584
+ page="$(jq -s --arg st "$state" --arg s "$since" --argjson n "$n" --argjson p "$page" "$sel"'if (.[-1] | length) == 100 and ([.[][] | select(keep)] | length) < $n and .[-1][-1].updated_at > $s then $p + 1 else 0 end' <<<"$pages")" || return
2585
+ done
2586
+ jq -cs --arg st "$state" --arg s "$since" --argjson n "$n" "$sel"'[.[][] | select(keep)] | sort_by(-.number) | .[:$n] | map({number, title, state: (if .merged_at then "MERGED" else (.state | ascii_upcase) end), headRefName: .head.ref, baseRefName: .base.ref, isDraft: (.draft // false), url: .html_url, updatedAt: .updated_at, author: {login: (.user.login // "")}, headRefOid: .head.sha, mergedAt: .merged_at})' <<<"$pages"
2587
+ }
2588
+
2589
+ # THE ARGUMENTS OF `pr-merged`, `pr-merge-commit`, `pr-merge-dest` and
2590
+ # `pr-merged-heads`: a branch, then `--repo <owner/repo>` at most. Sets `ref` and
2591
+ # `repo_args`; a missing branch or any other argument ends the script.
2592
+ op_branch_args() {
2593
+ ref="${1:?$op needs a branch}"; shift; repo_args=()
2594
+ while [ $# -gt 0 ]; do
2595
+ case "$1" in
2596
+ --repo) repo_args=(-R "${2:?}"); shift 2 ;;
2597
+ *) die "$op: unknown arg $1" ;;
2598
+ esac
2599
+ done
2558
2600
  }
2559
2601
 
2560
2602
  # `owner/repo` from the `origin` URL, with no host call. An `ssh://` URL may carry
@@ -4213,13 +4255,7 @@ case "$op" in
4213
4255
  # deciding whether to remove something. Exit 3 is still reserved for the call
4214
4256
  # itself failing in a way this adapter does not recognise as a miss.
4215
4257
  pr-merged)
4216
- ref="${1:?pr-merged needs a branch}"; shift || true; repo_args=()
4217
- while [ $# -gt 0 ]; do
4218
- case "$1" in
4219
- --repo) repo_args=(-R "${2:?}"); shift 2 ;;
4220
- *) die "pr-merged: unknown arg $1" ;;
4221
- esac
4222
- done
4258
+ op_branch_args "$@"
4223
4259
  # NO REMOTE, NO PR: no repository holds one, so nothing merged, whatever gh's auth says.
4224
4260
  if [ ${#repo_args[@]} -eq 0 ] && [ -z "$(git remote 2>/dev/null)" ]; then echo "not-merged"; else
4225
4261
  if [ "$be" = "github" ]; then
@@ -4286,13 +4322,7 @@ case "$op" in
4286
4322
  # `pr_list_report_truncation`. Bitbucket's arm already pages in full via
4287
4323
  # `_bb_paged_walk` (#2484); its `mergedAt` is `updated_on` as in `pr-list`,
4288
4324
  # since the endpoint carries no real merge timestamp (#2202).
4289
- ref="${1:?$op needs a branch}"; shift || true; repo_args=()
4290
- while [ $# -gt 0 ]; do
4291
- case "$1" in
4292
- --repo) repo_args=(-R "${2:?}"); shift 2 ;;
4293
- *) die "$op: unknown arg $1" ;;
4294
- esac
4295
- done
4325
+ op_branch_args "$@"
4296
4326
  if [ "$op" = pr-merge-dest ]; then pick='.[] | [.n, .b, .s, .t] | @tsv'; else pick='first.s // empty'; fi
4297
4327
  if [ "$be" = "github" ]; then
4298
4328
  limit=100
@@ -4344,13 +4374,7 @@ case "$op" in
4344
4374
  # A FAILURE WITH NO MESSAGE IS A FAILURE HERE, unlike `pr-state`: an empty
4345
4375
  # answer makes the caller fall back to a patch-id reading, so silence must
4346
4376
  # not stand in for *no merged head*. Only a recognised lookup miss is empty.
4347
- ref="${1:?pr-merged-heads needs a branch}"; shift || true; repo_args=()
4348
- while [ $# -gt 0 ]; do
4349
- case "$1" in
4350
- --repo) repo_args=(-R "${2:?}"); shift 2 ;;
4351
- *) die "pr-merged-heads: unknown arg $1" ;;
4352
- esac
4353
- done
4377
+ op_branch_args "$@"
4354
4378
  if [ "$be" = "github" ]; then
4355
4379
  if out="$(gh ${repo_args[@]+"${repo_args[@]}"} pr list --head "$ref" --state all --limit 100 --json mergedAt,headRefOid 2>"$HOST_ERR")"; then
4356
4380
  rm -f "$HOST_ERR"
@@ -4667,6 +4691,18 @@ case "$op" in
4667
4691
  failing_checks:[]}'
4668
4692
  exit 0
4669
4693
  fi
4694
+ # ONE CALL FOR ALL THREE ARMS, and the arm decides only the fields and the
4695
+ # projection. The plain fields always travel; `--rich` adds the verdicts,
4696
+ # and the rollup only where CI is not Jenkins (the Jenkins arm discards it).
4697
+ # THE FIELD ORDER IS THE QUERY `gh` SENDS, and the corpus pins it
4698
+ # (`github-pr-listing.ts`'s fragments), so each arm keeps its own order.
4699
+ # `gh_pr_list_routed` asks GraphQL or REST; a rich call is GraphQL always.
4700
+ _json=number,title,state,headRefName,baseRefName,isDraft,url,updatedAt,author,headRefOid,mergedAt
4701
+ [ "$rich" = 1 ] && _json="number,title,state,headRefName,baseRefName,isDraft,$([ "$ci" = jenkins ] || echo statusCheckRollup,)mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt"
4702
+ _gh_raw="$(pr_list_call gh_pr_list_routed gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} ${head_args[@]+"${head_args[@]}"} \
4703
+ --json "$_json")" || exit $?
4704
+ pr_list_report_truncation github "$limit" "$state" \
4705
+ "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4670
4706
  if [ "$rich" = 1 ]; then
4671
4707
  # `checks` has FOUR states, and two of them mean "a person is the
4672
4708
  # blocker" rather than "a machine is busy":
@@ -4749,10 +4785,6 @@ case "$op" in
4749
4785
  # $jstatus != "ok" → Jenkins could not answer; every row `unknown`.
4750
4786
  # $jentry == null → the branch has no Jenkins job; `none`.
4751
4787
  # otherwise → the joined colour's `checks`, job named on fail.
4752
- _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} ${head_args[@]+"${head_args[@]}"} \
4753
- --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4754
- pr_list_report_truncation github "$limit" "$state" \
4755
- "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4756
4788
  # GAPS 3/4/10: `jmap` names no commit, so a push between builds would
4757
4789
  # carry the OLD head's colour onto the new one. The bundle names the
4758
4790
  # rows `jmap` cannot settle (green/failing with a head sha, at most
@@ -4781,7 +4813,7 @@ case "$op" in
4781
4813
  # own field rather than collapsing into the same `checks` word
4782
4814
  # (`bitbucket-jenkins-a-pr-list-row`).
4783
4815
  {
4784
- number:.number, title:.title, state:.state, head:.headRefName,
4816
+ number:.number, title:.title, state:.state, head:.headRefName, base:(.baseRefName // ""),
4785
4817
  draft:.isDraft,
4786
4818
  checks:(if $jstatus != "ok" then "unknown" elif $eff == null then (if $ambiguous then "unknown" else "none" end) else $eff.checks end),
4787
4819
  mergeable:mergeable_of,
@@ -4794,13 +4826,9 @@ case "$op" in
4794
4826
  } + (if $jstatus == "ok" and $ambiguous and $eff == null then {checksLookup:"skipped"} else {} end)'
4795
4827
  else
4796
4828
  # GitHub without Jenkins (or Jenkins not configured): use GitHub rollup
4797
- _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} ${head_args[@]+"${head_args[@]}"} \
4798
- --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4799
- pr_list_report_truncation github "$limit" "$state" \
4800
- "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4801
4829
  printf '%s' "$_gh_raw" \
4802
4830
  | jq -c "$CHECKS_OF$MERGEABLE_OF"'.[] | {
4803
- number:.number, title:.title, state:.state, head:.headRefName,
4831
+ number:.number, title:.title, state:.state, head:.headRefName, base:(.baseRefName // ""),
4804
4832
  draft:.isDraft,
4805
4833
  checks:checks_of, mergeable:mergeable_of,
4806
4834
  review:(.reviewDecision // ""),
@@ -4825,12 +4853,8 @@ case "$op" in
4825
4853
  # advances its watermark by. Without it a split full read would leave
4826
4854
  # the store unable to narrow and the daily full read would never fall
4827
4855
  # due against anything but a cold window.
4828
- _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} ${head_args[@]+"${head_args[@]}"} \
4829
- --json number,title,state,headRefName,isDraft,url,updatedAt,author,headRefOid,mergedAt)" || exit $?
4830
- pr_list_report_truncation github "$limit" "$state" \
4831
- "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
4832
4856
  printf '%s' "$_gh_raw" \
4833
- | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),author:(.author.login // "")}'
4857
+ | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,base:(.baseRefName // ""),draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),headSha:(.headRefOid // ""),mergedAt:(.mergedAt // ""),author:(.author.login // "")}'
4834
4858
  fi
4835
4859
  else
4836
4860
  # `headSha` IS `.source.commit.hash`, which the pullrequests endpoint
@@ -5786,7 +5810,15 @@ case "$op" in
5786
5810
  printf '%s' "$body" | jq -c '.[] | {name, released: (.released // false), releaseDate: (.releaseDate // null)}' || exit 3 ;;
5787
5811
 
5788
5812
  pr-body)
5789
- num="${1:?pr-body needs a PR number}"; shift; pr_text_args pr-body "$@"
5813
+ num="${1:?pr-body needs a PR number}"; shift
5814
+ # WITH NO FLAG IT READS: it prints the PR's body, "" where it has none.
5815
+ # GitHub reads `GET pulls/<n>` over REST; Bitbucket reads `description`.
5816
+ if [ $# -eq 0 ]; then
5817
+ if [ "$be" = "github" ]; then gh_api_harvest "repos/$(gh_origin_slug)/pulls/$num" | jq -r '.body // ""'
5818
+ else bb_require_json; bb pr view "$num" --json | jq -r '.description // ""'; fi
5819
+ exit
5820
+ fi
5821
+ pr_text_args pr-body "$@"
5790
5822
  [ -z "$title$base$head$draft" ] || die "pr-body takes only --body or --body-file"
5791
5823
  [ -n "$body" ] || die "pr-body needs --body or --body-file"
5792
5824
  # GITHUB REPLACES THE BODY OVER REST, `PATCH repos/<origin slug>/pulls/<n>`,
@@ -5799,57 +5831,6 @@ case "$op" in
5799
5831
  else bb pr edit "$num" --body "$body"; fi
5800
5832
  ;;
5801
5833
 
5802
- rate-limit)
5803
- # Report the remaining API budget, per API. GitHub has TWO separate budgets
5804
- # (GraphQL and REST/core), and exhausting one says nothing about the other.
5805
- # Bitbucket has a single budget and no way to query it, so it reports unknown.
5806
- #
5807
- # Output: JSON object with the remaining budget per API:
5808
- # {"graphql":{"remaining":N,"limit":N,"reset":N},"core":{"remaining":N,"limit":N,"reset":N}}
5809
- # where N is a number, or each field is "unknown" when the host cannot answer.
5810
- #
5811
- # `reset` is epoch seconds — when the budget resets. A caller that wants
5812
- # "time until reset" computes it from now.
5813
- #
5814
- # The call itself is FREE — `gh api rate_limit` consumes neither bucket.
5815
- # Measured 2026-08-27: three consecutive readings, all `used=0`.
5816
- #
5817
- # This op REPORTS; it does not decide. A caller that wants to fall back when
5818
- # one budget is spent reads this, compares remaining to zero, and acts.
5819
- if [ "$be" = "github" ]; then
5820
- if out="$(gh api rate_limit 2>"$HOST_ERR")"; then
5821
- rm -f "$HOST_ERR"
5822
- # The payload has `resources.graphql` and `resources.core`, each with
5823
- # `remaining`, `limit`, and `reset`. Extract the two we care about.
5824
- jq -c '{
5825
- graphql: {
5826
- remaining: .resources.graphql.remaining,
5827
- limit: .resources.graphql.limit,
5828
- reset: .resources.graphql.reset
5829
- },
5830
- core: {
5831
- remaining: .resources.core.remaining,
5832
- limit: .resources.core.limit,
5833
- reset: .resources.core.reset
5834
- }
5835
- }' <<<"$out"
5836
- else
5837
- host_err
5838
- # The host could not be asked. Report unknown rather than failing outright,
5839
- # because this is informational — a caller that cannot read the budget
5840
- # should proceed with the default path, not error out.
5841
- echo '{"graphql":{"remaining":"unknown","limit":"unknown","reset":"unknown"},"core":{"remaining":"unknown","limit":"unknown","reset":"unknown"}}'
5842
- echo "plot-host: rate-limit query failed: $err" >&2
5843
- fi
5844
- else
5845
- # Bitbucket has no budget reporting. `unknown` is not `zero` — a host that
5846
- # cannot answer the budget question must report unknown, because zero means
5847
- # *spent*, and a caller that reads "cannot ask" as "exhausted" will take
5848
- # the expensive fallback path forever.
5849
- echo '{"graphql":{"remaining":"unknown","limit":"unknown","reset":"unknown"},"core":{"remaining":"unknown","limit":"unknown","reset":"unknown"}}'
5850
- fi
5851
- ;;
5852
-
5853
5834
  limit)
5854
5835
  # WHAT IS THIS CONNECTOR'S LIMIT, AND HOW WELL DOES IT KNOW IT?
5855
5836
  #
@@ -6078,6 +6059,6 @@ case "$op" in
6078
6059
  gh_edit_or_post_comment "$cid" pr "$num" "${2:?pr-comment needs a body}" || gh_fail; rm -f "$HOST_ERR" ;;
6079
6060
 
6080
6061
  *)
6081
- die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|issue-status|issue-open|issue-label|issue-comment|issue-comment-read|issue-close|version-list|pr-body|pr-review|rate-limit|limit|ci-limit|spend-rate|commit-status|pr-comment)"
6062
+ die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|issue-status|issue-open|issue-label|issue-comment|issue-comment-read|issue-close|version-list|pr-body|pr-review|limit|ci-limit|spend-rate|commit-status|pr-comment)"
6082
6063
  ;;
6083
6064
  esac
@@ -107,9 +107,9 @@ die() { echo "plot-release-refs: $*" >&2; exit 2; }
107
107
  command -v git >/dev/null 2>&1 || die "git not found"
108
108
  git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository"
109
109
 
110
- # The SAME gate the reaper uses, sourced rather than re-derived. `pr_merged`
111
- # reads `mergedAt` on ANY PR (never `state`, never ancestry); `pr_open` answers
112
- # the veto in guard 3.
110
+ # The SAME lookups the reaper uses, sourced rather than re-derived:
111
+ # `_plot_merged_lookup` reads `mergedAt` on ANY PR (never `state`, never
112
+ # ancestry), and `_plot_open_lookup` answers the open-PR veto.
113
113
  . "$script_dir/plot-pr-merged.sh"
114
114
 
115
115
  cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
@@ -169,27 +169,17 @@ fi
169
169
  # that estate may hold dozens of trees. The answer cannot change underneath a
170
170
  # single run in a way that matters — a worktree created mid-run holds a branch
171
171
  # whose ref this run has not yet reached, and the next run sees it.
172
- #
173
- # THE TREE'S STATE IS COLLECTED TOO, and that is what the shared rule needed.
174
- # `finishedWith` answers four conditions from a worktree, and it answers them
175
- # `unknown` where there is none — so it has to be told whether one was found.
176
- # That is a reading, not a refusal: this script asks none of those four, and
177
- # passing the tree is what lets the rule say `unknown` instead of inventing
178
- # `false`. Git's own `prunable` distinguishes a listed tree whose directory is
179
- # gone from one that was never made; both are unaskable, and the rule keeps the
180
- # two words apart because an operator acts on them differently.
181
172
  checked_out=$(git worktree list --porcelain 2>/dev/null \
182
- | awk '/^worktree /{wt=substr($0,10); pr="no"}
183
- /^prunable/{pr="yes"}
184
- /^branch refs\/heads\//{print substr($0,19) "\t" wt "\t" pr}')
173
+ | awk '/^worktree /{wt=substr($0,10)}
174
+ /^branch refs\/heads\//{print substr($0,19) "\t" wt}')
185
175
 
186
- # The worktree holding a branch and whether git calls it prunable, or empty
187
- # when no tree holds it.
176
+ # The worktree holding a branch, or empty when no tree holds it.
188
177
  worktree_of() {
189
- printf '%s\n' "$checked_out" | awk -F'\t' -v b="$1" '$1 == b {print $2 "\t" $3; exit}'
178
+ printf '%s\n' "$checked_out" | awk -F'\t' -v b="$1" '$1 == b {print $2; exit}'
190
179
  }
191
180
 
192
181
  released=0; kept=0; deleted=0
182
+ remote=$(git ls-remote --heads origin 2>/dev/null) || remote=unread
193
183
  printf '%-8s %-52s %s\n' "verdict" "branch" "why"
194
184
 
195
185
  # Branch and its deferred flag, one per line, from the plan's own parser.
@@ -205,115 +195,61 @@ while IFS=$'\t' read -r br deferred; do
205
195
  # `if` about whether a ref may go — only about which conditions it asks and
206
196
  # what to do with the answers.
207
197
  #
208
- # `pr_merged` reads `mergedAt` on ANY PR (never `state`, never ancestry) and
209
- # answers false when the host cannot be asked, so silence keeps the ref.
210
- # `pr_open` is asked separately rather than derived from it: a branch carries
211
- # both, and `changeset-release/main` is the measured case.
212
- merge=not-merged
213
- pr_merged "$br" && merge=merged
198
+ # A REF ORIGIN DOES NOT HOLD HAS NOTHING TO RELEASE, and asking the host about
199
+ # it only spends the limit. A listing that failed asks the host as before.
200
+ if [ "$remote" != unread ] && ! awk -v r="refs/heads/$br" '$2 == r {f=1} END {exit !f}' <<<"$remote"; then
201
+ printf '%-8s %-52s %s\n' "absent" "$br" "no remote ref — nothing to release"; continue
202
+ fi
214
203
 
215
- open_pr=false
216
- pr_open "$br" && open_pr=true
204
+ # Each lookup answers `found`, `none` or `unaskable`. `merge` reads `mergedAt`
205
+ # on ANY PR (never `state`, never ancestry); the open PR is asked separately
206
+ # because a branch carries both, and `changeset-release/main` is the measured
207
+ # case. An `unaskable` answer from either keeps the ref under its own name.
208
+ merge=$(_plot_merged_lookup "$br")
209
+ open_pr=$(_plot_open_lookup "$br")
217
210
 
218
- # WHETHER A TREE HOLDS THE BRANCH, AND IN WHAT STATE. Three words, because
219
- # the rule answers its four tree-sourced conditions `unknown` without one and
220
- # `unknown` is a reading rather than a failure. `vanished` is git's own
221
- # `prunable`: it reads like `absent` to every condition — there is equally
222
- # nothing to measure — and stays a separate word because `git worktree prune`
223
- # is the repair for one and not the other.
224
- #
225
- # NOTHING INSIDE THE TREE IS READ. A live pid, an uncommitted file and a
226
- # `PLOT-BLOCKED` marker are the reaper's three conditions and this script
227
- # asks none of them; measuring them here would put a refusal within one edit's
228
- # reach of a licence written narrow on purpose. A checked-out branch keeps its
229
- # ref whatever is going on inside it, which is guard 4 and needs no reading
230
- # from the tree at all.
231
- wt_line=$(worktree_of "$br")
232
- wt=${wt_line%%$'\t'*}
233
- prunable=${wt_line#*$'\t'}
234
- tree=absent
235
- if [ -n "$wt" ]; then
236
- if [ "$prunable" = "yes" ] || [ ! -d "$wt" ]; then tree=vanished; else tree=present; fi
237
- fi
211
+ # WHETHER A WORKTREE HOLDS THE BRANCH. Nothing inside the tree is read: a live
212
+ # pid, an uncommitted file and a `PLOT-BLOCKED` marker are the reaper's
213
+ # conditions, and this script passes them empty so they never refuse. A
214
+ # checked-out branch keeps its ref whatever is going on inside it.
215
+ wt=$(worktree_of "$br")
238
216
 
239
- # THE DECISION. `packages/domain/src/rules/reapable.ts`, imported directly —
240
- # the same shape and the same reason as `plot-reap.sh`: node 24 strips the
241
- # types, so there is no build step between this script and the rule, and the
242
- # JS arrives on STDIN from a QUOTED heredoc so the shell expands none of it.
243
- #
244
- # ONE RULE, TWO CALLERS, AND THE CALLERS STAY DIFFERENT. `finishedWith`
245
- # STATES every condition that can hold a desk and JUDGES none of them; which
246
- # conditions refuse a ref is this caller's half, and it names exactly the five
247
- # this script has always asked. The reaper reads the same rule and names its
248
- # own. Neither script gains the other's, which is what makes the difference
249
- # visible instead of eliminating it.
250
- #
251
- # `unknown` PERMITS, AND THE ORDER OF THE TESTS IS THE ARGUMENT. Only the
252
- # first two conditions are answerable without a tree, and 69% of branches have
253
- # none. `=== "true"` is therefore the test at every guard: `unknown` falls
254
- # through, exactly as this script behaved before the rule existed. That is
255
- # deliberate and it is the caller's decision to make — the reaper reads the
256
- # same `unknown` as *nothing to reap*.
217
+ # THE DECISION. `firstRefRefusal` in `packages/domain/src/rules/reapable.ts`,
218
+ # imported directly: node strips the types, so there is no build step between
219
+ # this script and the rule, and the JS arrives on STDIN from a QUOTED heredoc
220
+ # so the shell expands none of it. The rule names the first refusal in its
221
+ # own order; a host that could not be asked refuses as `merge-unaskable` or
222
+ # `open-unaskable`.
257
223
  #
258
224
  # A rule that cannot be asked REFUSES: node missing, the import failing, the
259
225
  # module throwing all leave `verdict` empty, and an empty verdict keeps the
260
- # ref and says why. Silence is never permission on this path either — that is
261
- # the module being absent, which is not the same reading as a condition
262
- # answering `unknown`.
226
+ # ref and says why.
263
227
  verdict=$(PLOT_BRANCH="$br" PLOT_DEFAULT="$DEFAULT" PLOT_MERGE="$merge" \
264
228
  PLOT_GIVEN_UP="$deferred" PLOT_OPEN_PR="$open_pr" \
265
- PLOT_TREE="$tree" \
266
229
  PLOT_CHECKED_OUT="$([ -n "$wt" ] && echo true || echo false)" \
267
230
  PLOT_RULE="$RULE_PATH" \
268
231
  node --input-type=module - <<'NODE_EOF' 2>/dev/null
269
- // An ABSOLUTE path derived from this script, never from the cwd: this runs
270
- // wherever the operator invoked it, and the reconcile suite runs it against
271
- // sandbox repos in the temp directory.
232
+ // An ABSOLUTE path derived from this script, never from the cwd.
272
233
  //
273
- // NO APOSTROPHE MAY APPEAR ANYWHERE IN THIS BLOCK. bash 3.2 is /bin/bash on
274
- // macOS, and it is what the reconcile suite runs this script under when it
275
- // strips PATH. It parses the body of a quoted heredoc nested inside `$(...)`,
276
- // so one contraction opens a string that never closes and the whole file fails
277
- // to parse. The error reads `unexpected EOF` and names a line 30 further down,
278
- // which points nowhere near the apostrophe.
279
- const { finishedWith } = await import(process.env.PLOT_RULE);
280
-
281
- const held = finishedWith({
282
- branch: process.env.PLOT_BRANCH,
283
- defaultBranch: process.env.PLOT_DEFAULT,
284
- // This script never looks at the main checkout as a tree; the branch test
285
- // the rule makes is what catches the default branch.
234
+ // NO APOSTROPHE MAY APPEAR ANYWHERE IN THIS BLOCK. bash 3.2 parses the body of
235
+ // a quoted heredoc nested inside `$(...)`, so one contraction opens a string
236
+ // that never closes and the whole file fails to parse.
237
+ const { firstRefRefusal } = await import(process.env.PLOT_RULE);
238
+ const e = process.env;
239
+ const refusal = firstRefRefusal({
240
+ branch: e.PLOT_BRANCH,
241
+ defaultBranch: e.PLOT_DEFAULT,
286
242
  isMain: false,
287
- // The three the reaper measures and this script does not. They are passed
288
- // empty because the rule shape asks for them, and the tree reading below is
289
- // what makes them honest: with no tree they answer `unknown`, and this
290
- // caller reads none of the three either way.
291
243
  workerPid: null,
292
244
  dirtyPath: "",
293
245
  blockedMarker: false,
294
- merge: process.env.PLOT_MERGE,
295
- givenUp: process.env.PLOT_GIVEN_UP === "true",
296
- openPr: process.env.PLOT_OPEN_PR === "true",
297
- checkedOut: process.env.PLOT_CHECKED_OUT === "true",
298
- tree: process.env.PLOT_TREE,
246
+ merge: { found: "merged", none: "not-merged" }[e.PLOT_MERGE] ?? "unreachable",
247
+ givenUp: e.PLOT_GIVEN_UP === "true",
248
+ openPr: e.PLOT_OPEN_PR === "found",
249
+ openPrUnaskable: e.PLOT_OPEN_PR === "unaskable",
250
+ checkedOut: e.PLOT_CHECKED_OUT === "true",
299
251
  });
300
-
301
- // THE FIVE GUARDS, in the order they have always been tested, and each
302
- // satisfied only by a condition answering `true`. `unknown` permits: it means
303
- // no evidence against deletion, which on this estate is the majority reading
304
- // and the one the script already acted on. `liveWorker`, `uncommittedChanges`
305
- // and `blockedMarker` are in `held` and are deliberately not consulted.
306
- const guards = [
307
- ["given-up", held.givenUp, ""],
308
- ["no-merged-pr", held.noMergedPr, ""],
309
- ["open-pr", held.openPr, ""],
310
- ["checked-out", held.checkedOut, ""],
311
- ["on-default-branch", held.onDefaultBranch, process.env.PLOT_DEFAULT],
312
- ];
313
-
314
- const refusal = guards.find(([, reading]) => reading === "true");
315
-
316
- process.stdout.write(refusal === undefined ? "delete\t" : `${refusal[0]}\t${refusal[2]}`);
252
+ process.stdout.write(refusal === null ? "delete\t" : `${refusal.refusal}\t${refusal.detail}`);
317
253
  NODE_EOF
318
254
  )
319
255
 
@@ -324,7 +260,9 @@ NODE_EOF
324
260
  # produce is empty, and an empty refusal keeps the ref and says so.
325
261
  case "$refusal" in
326
262
  given-up) why="deferred — a given-up branch keeps its ref" ;;
263
+ merge-unaskable) why="the host could not be asked whether a PR merged" ;;
327
264
  no-merged-pr) why="unlanded work — no merged PR" ;;
265
+ open-unaskable) why="the host could not be asked for an open PR" ;;
328
266
  open-pr) why="an open PR is using this branch" ;;
329
267
  checked-out) why="checked out in a worktree — somebody is reading it" ;;
330
268
  on-default-branch) why="the default branch — never deleted" ;;
@@ -240,8 +240,8 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
240
240
  echo " usage: plot-state-receipt.sh --unowned-action <dispatch|approve|deliver|release|restart> <subject> <reason>" >&2
241
241
  echo "" >&2
242
242
  echo " The reason is required because each use names a routing gap, and a gap" >&2
243
- echo " nobody wrote down is one nobody closes. Where the board IS running, the" >&2
244
- echo " controller is the route and this is not needed." >&2
243
+ echo " nobody wrote down is one nobody closes. Where the controller command" >&2
244
+ echo " exists, it is the route and this is not needed." >&2
245
245
  exit 2
246
246
  fi
247
247
  # The action word, or the script name — an operator reaching for this has
@@ -271,7 +271,7 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
271
271
  echo "plot-state-receipt: recorded an UNOWNED action — $action_script $action_subject"
272
272
  echo " reason: $action_reason"
273
273
  echo " This clears plot-controller-gate.sh for one run of that script. The controller"
274
- echo " is still the route: this exists for a machine running no board."
274
+ echo " command is still the route: this exists where it cannot run."
275
275
  exit 0
276
276
  fi
277
277
 
@@ -284,7 +284,7 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
284
284
  echo " /plot-release writing 'State: Released'" >&2
285
285
  echo "" >&2
286
286
  echo "--unowned-action is the other layer: a controller-owned action run with no" >&2
287
- echo "controller, for a machine running no board." >&2
287
+ echo "controller command, where it cannot run." >&2
288
288
  echo "" >&2
289
289
  echo "Every other State: write has a command that owns it. Use that command." >&2
290
290
  exit 2