@plot-pm/board 0.9.1 → 0.11.0

package/plot-fleet-scan.sh

@@ -2,13 +2,17 @@
 # Plot helper: fleet pulse — deterministic extractor for wave/claim state.
 # Usage: plot-fleet-scan.sh [--no-fetch] [--offline] [--next] [<slug>]
 #   --no-fetch  skip `git fetch`
-#   --offline   same (no network) — used for cheap, ambient pulses.
+#   --offline   same (no fetch) — used for cheap, ambient pulses.
 #               The fetch also PRUNES remote-tracking refs, so skipping it
 #               keeps whatever stale refs this checkout holds: a branch merged
 #               and deleted upstream may read `wip` rather than `merged`, and
 #               its wave may read blocked. That is the honest answer for a scan
 #               that asked nothing, and the footer says so rather than leaving
 #               it to be discovered.
+#               IT DOES NOT SILENCE THE HOST ON THE OFFER PATH. With `--next`
+#               or `--list-eligible` the host is asked anyway — see those flags
+#               — because naming a branch to claim turns on a fact refs cannot
+#               supply. Every other use of the flag asks nothing, as before.
 #   --list-eligible  print EVERY claimable branch, one per line (exit 1 if none).
 #               For callers that need the count rather than one item — a dry
 #               run changes nothing, so its answer cannot go stale.
@@ -24,12 +28,27 @@
 #               exit 1 when there is none. Used by /plot-implement to pick work
 #               without re-deriving eligibility. "Nothing to start" is a normal
 #               state — the exit code, not stderr, is what says so.
+#               ASKS THE HOST EVEN UNDER `--offline`, and withholds a branch it
+#               could not ask about. A merged branch is not claimable, and once
+#               a squash merge has rewritten the commits and `--delete-branch`
+#               has removed the ref, the host is the only source that can say
+#               so. Measured 2026-09-04: ten refs on this estate carry the tip
+#               commit `plot: claim <branch>` dated hours AFTER their own merge,
+#               all pushed on this offer.
+#   --why-nothing  print WHY `--next` would be silent, and exit 0 either way:
+#               `none` when there is no work left for this plan, or `not-yet`
+#               followed by the branches whose landing would open a blocked
+#               slice. THE SECOND QUESTION A WORKER ASKS. `--next` exits 1 for
+#               two different nothings — a blocked next slice and no next slice
+#               — and a worker that cannot tell them apart pays a whole
+#               dispatch to reach a slice it was standing next to. Exits 0 with
+#               `none` when it cannot tell, so silence is never read as wait.
 #   --stream    --json, emitted as it resolves rather than as one document at
 #               the end. One `{"kind":"plan","plan":{...}}` line per plan the
 #               moment that plan is fully derived, then one
-#               `{"kind":"pulse","pulse":{...}}` line carrying the SAME
+#               `{"kind":"reading","reading":{...}}` line carrying the SAME
 #               document --json prints. A consumer that has seen plan lines and
-#               no pulse line holds a PARTIAL answer — the scan takes 18 s on
+#               no reading line holds a PARTIAL answer — the scan takes 18 s on
 #               84 branches and a board that renders nothing for that long
 #               looks broken. The terminal line is what says the scan finished;
 #               a closed pipe does not, because a killed scan closes it too.
@@ -46,13 +65,48 @@
 #               differs, and a terminal-phase plan lands here too (it is not
 #               approved); the board routes those to DONE by phase before the
 #               verdict is read.
+# Branch states — the word each BRANCH carries, distinct from the wave verdicts
+# above. `open`, `wip`, `merged`, `claimed`, `deferred` and `unknown` are read
+# from git and the host. Two more are read from the plan's `waits:` annotation:
+#   waiting     the branch names a prerequisite branch that has not merged. A
+#               wait with an end: it clears when that branch lands, and the
+#               fleet payload carries `waits_on` so a reader sees on WHAT.
+#   blocked     the branch names a prerequisite the host has never seen a PR
+#               for — a typo, or a branch nobody created. A defect in the plan
+#               estate, not progress, which is why it is a separate word: the
+#               first resolves by waiting, the second by editing the plan.
+#               THE SAME WORD AS THE WAVE VERDICT, IN A DIFFERENT VOCABULARY.
+#               A wave is `blocked` by an earlier wave; a branch is `blocked`
+#               by a prerequisite nobody declared. The two travel in separate
+#               JSON fields (`waves[].verdict` vs `branches[].state`) and are
+#               counted separately in the footer — `blocked=` is the wave
+#               count it has always been, `prereq_missing=` is the branch one.
+# Both apply ONLY where the branch's own state is `open` or `unknown` — a
+# branch carrying work, a claim, or a merge has already been started, and
+# overriding `merged` would stop its wave settling forever. An unreachable host
+# holds the slice at `waiting`; silence is never permission to start, and never
+# evidence of a typo either.
 # Output: per-plan wave report on stdout, terminated by a machine-countable
 #         summary line:
-#             summary: plans=1 waves=3 branches=5 claimed=1 eligible=2 blocked=1 deferred=1 merge_detect=pr-merge main=main
+#             summary: plans=1 waves=3 branches=5 claimed=1 eligible=2 blocked=1 deferred=1 waiting=1 prereq_missing=0 merge_detect=pr-merge host=ok main=main
+#         `blocked` counts WAVES an earlier wave holds; `waiting` and
+#         `prereq_missing` count BRANCHES their `waits:` annotation holds.
 #         merge_detect names how merged-and-deleted branches were detected:
 #         pr-merge (exhaustive), truncated (capped walk), none (no conforming
 #         merge commits — a squash/rebase repo, where `open` says nothing about
 #         merging).
+#         host says whether the git host ANSWERED, and is what says whether
+#         merge_detect can be believed: ok (the list arrived — an EMPTY list is
+#         ok, the host answered and there are none), throttled (a spent quota;
+#         the same question after the reset will be answered), secondary (a
+#         burst refusal, which clears in seconds), failed (any other failure),
+#         unasked (no host, or --offline — the question was never put, which is
+#         not the same as one that went unanswered).
+#         Measured 2026-08-30: a merged branch read `open` and was counted
+#         among the unfinished under `merge_detect=pr-merge`, which reads as
+#         *asked and answered*, while the host had refused every call. Where
+#         host is throttled, secondary or failed, a no-ref branch reads `unknown`
+#         rather than `open` and is not offered to --next.
 #         Consumers that only need counts (the /plot-fleet pulse log, the
 #         board) read that one line and never re-count the body.
 #         --json additionally carries, per PLAN, `phase` — the plan's own
@@ -159,6 +213,7 @@ cfg() { "$script_dir/plot-config.sh" get "$1" "${2:-}"; }
 do_fetch=1
 next_only=0
 list_all=0
+why_nothing=0
 loose=0
 log_pulse=0
 as_json=0
@@ -171,6 +226,11 @@ while [ $# -gt 0 ]; do
     --log-pulse) log_pulse=1 ;;
     --next) next_only=1 ;;
     --list-eligible) next_only=1; list_all=1 ;;
+    # THE SECOND QUESTION, and it borrows `--next`'s population deliberately.
+    # A caller asks this having just been told nothing, so it must be told
+    # about the SAME plans `--next` was silent over — a terminal plan admitted
+    # here would answer `not-yet` about work somebody decided was not needed.
+    --why-nothing) next_only=1; why_nothing=1 ;;
     --json) as_json=1 ;;
     --stream) as_json=1; stream=1 ;;
     -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
@@ -390,8 +450,39 @@ fi
 # host would be lying in the direction of a slow ambient pulse. Without a
 # backend — or offline — the lookup is simply never attempted and every branch
 # answers exactly as it did before.
+#
+# THE OFFER IS THE EXCEPTION, AND IT IS NARROW. `--next` and `--list-eligible`
+# do not report an estate; they name a branch a worker is about to CLAIM by
+# pushing a ref. That question cannot be answered from refs alone, because the
+# fact it turns on — did this branch's PR merge — is one only the host holds
+# once a squash merge has rewritten the commits and `--delete-branch` has taken
+# the ref away.
+#
+# WHAT `--offline` ACTUALLY PROMISES IS NO FETCH. Everything else followed from
+# `do_fetch` because the two were one flag, and that conflation is the defect.
+# Measured 2026-09-04 on this estate, from `plot-worker-loop.sh`'s own call:
+#
+#   plot-fleet-scan.sh --offline --next the-domain-owns-the-agent-lifecycle
+#     → feature/an-agent-declares-what-it-is
+#
+# whose PR #679 merged at 20:46 the previous evening. The same scan WITHOUT
+# `--offline` read that branch `merged`, its slice `complete`, and named
+# nothing. Five of that plan's eight branches moved between the two readings.
+# Ten refs across four days carry the tip commit `plot: claim <branch>` dated
+# hours AFTER their own merge — this offer is what pushed every one of them.
+#
+# THE AMBIENT PULSE IS UNTOUCHED. `--offline` without `--next` still asks
+# nothing, so the 5 s board poll and the cheap operator glance keep the cost
+# they were given the flag for. The call is one repo-wide `pr-list`, already
+# cached per run, and it is paid only by a caller asking to be handed work —
+# which is about to spend a worker on the answer.
+#
+# NO BACKEND STILL MEANS NO LOOKUP. A repo with no git host has no merge state
+# to withhold on, and refusing there would stop `--next` in every fixture and
+# every hostless checkout. The `backend` test below is what keeps that case
+# working, and it is the only condition the offer path drops.
 HOST_LOOKUP_OK=0
-if [ "$do_fetch" = 1 ] \
+if { [ "$do_fetch" = 1 ] || [ "$next_only" = 1 ]; } \
    && [ "$("$script_dir/plot-host.sh" backend 2>/dev/null)" != "none" ]; then
   HOST_LOOKUP_OK=1
 fi
@@ -482,10 +573,36 @@ cache_key() { # $1=branch → a filename that is injective in the branch name
 # already performs on Bitbucket, so the join and the per-branch lookup cannot
 # disagree about the same branch.
 PR_LIST_LIMIT="${PLOT_PR_LIST_LIMIT:-1000}"
+
+# WHETHER THE HOST ANSWERED, as a fact of its own — the thing this scan
+# computed and threw away until 2026-08-30.
+#
+#   ok         — the list arrived. An EMPTY list is `ok`: the host answered and
+#                there are none. Collapsing that into a failure would trade a
+#                silent wrong answer for a noisy one and break every repo that
+#                genuinely has no PRs.
+#   throttled  — a SPENT QUOTA (`plot-host.sh` exit 5). Nothing is broken; the
+#                same question after the reset will be answered.
+#   secondary  — a burst refusal (`plot-host.sh` exit 6). Nothing is broken
+#                either, and it clears in seconds rather than minutes.
+#   failed     — any other failure (exit 3, or anything unclassified).
+#   unasked    — no host to ask, or --offline WITHOUT `--next`. Not a
+#                degradation: the scan was never going to ask, and saying
+#                `failed` would report a fault where there is a configuration.
+#                `--offline --next` DOES ask, so it reaches one of the words
+#                above rather than this one.
+#
+# THREE WORDS FOR THREE FAILURES BECAUSE THEY ASK FOR DIFFERENT RESPONSES.
+# `throttled` says wait for the reset; `secondary` says retry shortly and run
+# fewer at once; `failed` says look. An operator told to wait out an outage
+# loses exactly the time waiting was meant to save — and one told to wait out a
+# secondary limit waits minutes for a ceiling that cleared in seconds.
+HOST_VERDICT=unasked
+
 prefill_pr_states() {
   [ "$HOST_LOOKUP_OK" = 1 ] || return 0
   [ -n "$HOST_STATE_CACHE" ] || return 0
-  local js br st key
+  local js br st key rc
   # Exit code first: non-zero is a transport failure and its stdout is not an
   # answer. A failed list leaves the cache EMPTY, so every branch falls through
   # to the unanswerable `-` rather than to a fabricated "no PR".
@@ -497,8 +614,91 @@ prefill_pr_states() {
   # configured), and the parsing below already skips fields the response does
   # not contain. The BEHAVIOUR change is in `pr_ready`, which now reads the
   # check rollup from the cache rather than making a per-branch host call.
-  js=$("$script_dir/plot-host.sh" pr-list --state all --limit "$PR_LIST_LIMIT" --rich \
-         </dev/null 2>/dev/null) || return 0
+  #
+  # THE CODE IS KEPT, not just tested. This guard was always correct — a failed
+  # list prefills nothing — and until 2026-08-30 it never fired, because
+  # `pr-list` swallowed its own failure and exited 0 with empty stdout. Now
+  # that it can fail, WHICH failure it was is a fact worth carrying: exit 5 is
+  # a rate limit and exit 3 is anything else, and the summary reports the
+  # difference rather than degrading silently.
+  # STDOUT TO A FILE so stderr can be captured separately — see the verdict
+  # below. It lives in `HOST_STATE_CACHE`, which already has an EXIT trap, so
+  # this adds no second cleanup path. When mktemp -d failed the cache is "",
+  # and /dev/null keeps the call working with the text simply unavailable.
+  host_list_out="${HOST_STATE_CACHE:+$HOST_STATE_CACHE/pr-list.json}"
+  host_list_out="${host_list_out:-/dev/null}"
+  host_err=$("$script_dir/plot-host.sh" pr-list --state all --limit "$PR_LIST_LIMIT" --rich \
+         </dev/null 2>&1 >"$host_list_out"); rc=$?
+  js=$(cat "$host_list_out" 2>/dev/null)
+  if [ "$rc" -ne 0 ]; then
+    # THREE OUTCOMES, NOT TWO. `unasked` already means "the question was
+    # never put" (see HOST_VERDICT above: *not a degradation, the scan was
+    # never asking*), and a host that cannot be ASKED AT ALL belongs there
+    # rather than among answers that failed to arrive.
+    #
+    # THE EXIT CODE CANNOT SEPARATE THEM. `plot-host.sh:849` is explicit
+    # that a missing token is *"a CONFIG error the op cannot proceed past
+    # — exit 3, never"* exit 4, so an unauthenticated CLI and a genuine
+    # mid-answer failure arrive with the SAME status. The stderr text is
+    # the only thing that distinguishes them, and it is already in hand:
+    # a second probe call would cost another fork for a fact this one
+    # already produced.
+    #
+    # WHY IT MATTERS: `failed` makes every branch `unknown`, and `unknown`
+    # is not startable — so a checkout with no host credentials reports an
+    # estate on which nothing can be started. Measured 2026-08-31:
+    # `packages/board/test/claimed.test.mjs`, whose header says it *"never
+    # touches a network or a git host"*, read `eligible: 0` where it had
+    # always read 1. The branch was startable; the scan had stopped being
+    # able to say so.
+    case "$rc" in
+      5) HOST_VERDICT=throttled ;;
+      6) HOST_VERDICT=secondary ;;
+      4) HOST_VERDICT=unasked ;;
+      *) case "$host_err" in
+           # THE WORDING IS MEASURED, NOT GUESSED. An earlier version of this
+           # list matched auth/login/credential and MISSED the message CI
+           # actually emits:
+           #
+           #   "gh: To use GitHub CLI in a GitHub Actions workflow, set the
+           #    GH_TOKEN environment variable."
+           #
+           # which contains none of those words. The fix passed locally — where
+           # `gh` is authenticated and this branch never runs — and failed on
+           # every CI run. Measured 2026-08-31 against a stubbed `gh`.
+           #
+           # So the patterns name what the CLIs SAY when they have no identity:
+           # a token, a login, a credential, or authentication. Anything else is
+           # a real failure and stays `failed`, because widening this to a
+           # catch-all would turn every host outage into "nobody asked".
+           *TOKEN*|*token*|*auth*|*Auth*|*AUTH*|*login*|*Login*|*credential*|*Credential*|*"not logged"*)
+             HOST_VERDICT=unasked ;;
+           # NO REMOTE IS A CONFIGURATION, NOT A FAULT — the same reading as a
+           # missing token one line up, reached by the same route: `plot-host.sh`
+           # exits 3 for both, because both are "the op cannot proceed", and
+           # only the text separates them.
+           #
+           # `backend` ANSWERS `github` IN A REPO WITH NO REMOTE, which is what
+           # makes this reachable at all: the key is read from config, and a
+           # repo can name a host it has no repository on. So the backend test
+           # that gates the lookup cannot catch this case, and the failure
+           # arrives here instead.
+           #
+           # Measured 2026-09-04 against `test/reconcile/dispatch.test.mjs`'s
+           # `noRemote` fixture: `--list-eligible` withheld a branch nobody had
+           # started, because a host that does not exist read as one that
+           # failed. `failed` makes every branch `unknown` and `unknown` is not
+           # claimable — the right refusal about the wrong thing. There is no
+           # merge state to withhold on where there is no remote to hold it.
+           *"no git remotes"*|*"no remote"*)
+             HOST_VERDICT=unasked ;;
+           *) HOST_VERDICT=failed ;;
+         esac ;;
+    esac
+    return 0
+  fi
+  # The list arrived. An empty one arrived too — that is the whole distinction.
+  HOST_VERDICT=ok
   # `pr-list` emits one compact JSON object per line. PARSED IN ONE PASS, and
   # that is a correctness-of-cost property rather than a style preference:
   # measured 2026-08-18 on this repo's 221 PRs, a `sed` per field per row —
@@ -883,6 +1083,66 @@ reached_review() { # $1=branch → 0 when an open or merged PR exists
   case "$(host_pr_state "$1")" in OPEN|MERGED) return 0 ;; *) return 1 ;; esac
 }
 
+# ---------------------------------------------------------------------------
+# A SLICE THAT WAITS ON ANOTHER PLAN'S BRANCH
+# ---------------------------------------------------------------------------
+#
+# Slice eligibility is computed PER PLAN, so nothing here compares two plans —
+# and that is the defect this answers. Measured 2026-09-01, twice in one
+# session: the fleet offered a branch as claimable whose prerequisite lived in
+# a different plan and had not merged, and the only thing between a worker and
+# premature work was a paragraph in a brief.
+#
+# THE RUN-SCOPED CACHE, NEVER `terminal_cached`. There are two caches and only
+# one can answer this. `terminal_cached` is keyed by `TERMINAL_PLAN_OID` — the
+# plan revision the answer was derived under — and returns nothing unless that
+# oid is the plan CURRENTLY being walked. A prerequisite belongs to another plan
+# by construction, so its entry can never validate. `HOST_STATE_CACHE` is keyed
+# by branch name alone through `cache_key`, which makes it the only cache whose
+# key this question can form. `host_pr_state` reads and writes it before asking
+# the host, so a prerequisite the run visits for its own plan costs NOTHING the
+# second time.
+#
+# SO THE COST IS BOUNDED AND STATED: free where the prerequisite is visited
+# elsewhere in the run, ONE host call per run otherwise — never one per pass.
+#
+# THE QUESTION IS ASKED OF THE HOST, NOT OF THE REFS, and an earlier draft of
+# this rule would have deadlocked on SUCCESS. `plot-release-refs.sh` deletes the
+# remote refs of a delivered plan's merged branches, so a prerequisite that
+# COMPLETED eventually has no ref — and "no ref → blocked" would hold the
+# waiting slice forever because its dependency succeeded. A merged PR outlives
+# the branch it was cut from, which is why `plot-pr-merged.sh` reads PRs and not
+# refs, and why this reads the same source.
+#
+# THREE ANSWERS, and the third is the one that must not be collapsed into the
+# second:
+#
+#   | host says        | answer    | meaning                                  |
+#   |------------------|-----------|------------------------------------------|
+#   | MERGED           | ""        | cleared — the annotation stops mattering |
+#   | OPEN or CLOSED   | waiting   | a wait with an end                       |
+#   | NONE             | blocked   | no PR ever existed: a typo               |
+#   | `-` (unreachable)| waiting   | silence is not evidence, in EITHER       |
+#   |                  |           | direction: not permission to start, and  |
+#   |                  |           | not proof of a typo                      |
+#
+# A CLOSED, UNMERGED PR IS `waiting` RATHER THAN `blocked`: the host has seen
+# the branch, so nothing is misspelled — somebody withdrew the work, and that
+# resolves by reopening it, not by editing the plan.
+waits_state() { # $1=prerequisite branch → "waiting" | "blocked" | ""
+  local st
+  # `--ask` because the prerequisite is precisely the branch the repo-wide list
+  # may legitimately omit: its plan may be delivered and its ref gone. The
+  # bound is the same one PR #216 set — ABSENT branches, not all branches — and
+  # the cache above keeps it at one call per run.
+  st=$(host_pr_state "$1" --ask)
+  case "$st" in
+    MERGED) printf '' ;;
+    NONE)   printf 'blocked' ;;
+    *)      printf 'waiting' ;;
+  esac
+}
+
 # Modification time of a path, in epoch seconds, following symlinks — or "" when
 # it cannot be read.
 #
@@ -2401,9 +2661,15 @@ for line in sys.stdin:
             # run of tabs collapses to one separator and only the LAST field
             # may be optional. "-" stands in for empty everywhere, so no run
             # can form.
+            # THE PREREQUISITE, from the `waits_on` key the parser emits —
+            # never re-parsed from the annotation. The key is ABSENT on a branch that
+            # declares nothing (`plot-plan-meta.sh` promises "a branch name or
+            # nothing — never a blank string"), and "-" stands in here for the
+            # same tab-collapse reason every other middle column does.
             print("\t".join(clean(x) for x in [
                 "W", f, str(i), ref, str(b.get("deferred")).lower(),
                 (b.get("deferred_reason") or "-"),
+                (b.get("waits_on") or "-"),
                 name or "-", b.get("claimed") or "-"]))
 ' "$DELIVERED_WINDOW_HOURS" 2>/dev/null) || records=""
 
@@ -2617,13 +2883,18 @@ if [ ${#plans[@]} -eq 0 ]; then
   # the same answer whether the plans are all claimed or there are no plans at
   # all. Exiting 0 here would hand a caller an EMPTY branch name as if it were
   # valid work.
+  # `--why-nothing` answers here too, and it answers `none`. No plans means no
+  # slice can ever become eligible, which is the honest end of a worker's life
+  # — and a wait with nothing to wait on is the one failure this flag exists to
+  # prevent.
+  [ "$why_nothing" = 1 ] && { echo "none"; exit 0; }
   [ "$next_only" = 1 ] && exit 1
   # A MACHINE CONSUMER FALLS THROUGH. An empty estate is a COMPLETE answer, and
   # this branch used to end the run before the emitter — so `--json` and
   # `--stream` were ignored entirely here and a consumer got human prose on
-  # stdout. Under `--stream` that meant no terminal `pulse` line, and the
+  # stdout. Under `--stream` that meant no terminal `reading` line, and the
   # board's contract (":3407": *"a consumer that has seen `plan` lines and no
-  # `pulse` line has a PARTIAL answer and must say so"*) made it report a
+  # `reading` line has a PARTIAL answer and must say so"*) made it report a
   # complete answer as a scan failure — forever, because the next scan said the
   # same. Measured 2026-08-28 against a board installed from npm: *"fleet scan
   # ended without a terminal pulse line"*, `ready:false`, every pulse.
@@ -2638,7 +2909,7 @@ if [ ${#plans[@]} -eq 0 ]; then
     # the scan globbed it; pointing a reader at the index would now send them to
     # look for the cause of an empty list in a directory nothing consults.
     echo "No plans found in ${PLAN_DIR}."
-    echo "summary: plans=0 waves=0 branches=0 claimed=0 eligible=0 blocked=0 deferred=0 main=$MAIN"
+    echo "summary: plans=0 waves=0 branches=0 claimed=0 eligible=0 blocked=0 deferred=0 waiting=0 prereq_missing=0 main=$MAIN"
     exit 0
   fi
 fi
@@ -2766,6 +3037,37 @@ branch_state() {
     # a miss, a CLOSED PR, or a host that cannot answer all fall through to the
     # `open` below, exactly as before this call existed.
     merged_by_host "$br" && { echo "merged"; return; }
+    # `open` IS A CLAIM ABOUT A PR: that one was looked for and none was found.
+    # With no ref, the host is the only remaining source, so when it could not
+    # be asked that claim was never earned — and the branch measured on
+    # 2026-08-30 was merged while reading `open`, counted among the unfinished
+    # under `merge_detect=pr-merge`, which reads as *asked and answered*.
+    #
+    # `unknown` IS OUTSTANDING, exactly as `open` is — the `*)` arm of the wave
+    # arithmetic counts both, so no wave verdict moves and the degradation
+    # direction is untouched: an unreachable host still answers *not merged*,
+    # and silence is still never permission.
+    #
+    # WHAT IT DOES CHANGE IS CLAIMABILITY, and that is the fix rather than a
+    # side effect. `--next` offers branches whose state is `open`, so an
+    # `unknown` branch is not handed out — which is right, because "nobody has
+    # started this" is precisely the claim that went unverified. Handing out a
+    # merged branch is what actually happened.
+    #
+    # GATED ON THE THREE FAILURES ONLY, never on "not ok". `unasked` — no host
+    # configured, or --offline — must keep reading `open`: the scan was never
+    # going to ask, so nothing was lost, and flipping every unstarted branch to
+    # `unknown` on every offline scan would be a far larger change than the
+    # defect. A question that was not put is not a question that went
+    # unanswered.
+    #
+    # `secondary` GATES LIKE THE OTHER TWO, and its faster recovery is no reason
+    # to exempt it: the question was PUT and went unanswered, so this scan has
+    # no more evidence than a throttled one does. What the two limits differ in
+    # is what to DO about it, which is the note below and not this branch.
+    case "$HOST_VERDICT" in
+      throttled|secondary|failed) echo "unknown"; return ;;
+    esac
     echo "open"; return
   fi
   # A CLAIM is a branch whose only commits beyond main are claim commits —
@@ -2836,6 +3138,53 @@ branch_state() {
   fi
   # Nothing of its own. NOT a claim: that shape is indistinguishable from
   # merged work, which is exactly why claims carry a commit.
+  #
+  # ZERO AHEAD CARRIES TWO SHAPES, and only one of them is landed work:
+  #
+  #   | shape          | ancestry says           | truth         |
+  #   |----------------|-------------------------|---------------|
+  #   | behind main    | is an ancestor → merged | merged        |
+  #   | reset to main  | is an ancestor → merged | holds nothing |
+  #
+  # A branch pointing AT the default branch is trivially an ancestor of it, so
+  # every ancestry test passes — right for the case this arm was built for (a
+  # squash merge leaves the branch behind, and its work IS on main), and wrong
+  # for a branch that was reset, where the same shape means it holds NOTHING.
+  #
+  # Measured 2026-08-29: `feature/one-deliver-rule-decides-in-the-domain` was
+  # reset to `origin/main` so a worker could rebuild it, its PR (#511) having
+  # been CLOSED, never merged. Seconds later the scan reported the branch
+  # `merged`, completed its wave, and opened `Transitions` on the strength of
+  # work that does not exist. `merged` is the state that SETTLES a wave, so
+  # this error does not stall the fleet — it advances it onto a seam nobody
+  # wrote, which is the worse direction.
+  #
+  # THE DISCRIMINATOR IS THE OTHER DIRECTION. A branch with zero commits ahead
+  # is either equal to the default branch or a strict ancestor of it, so
+  # "behind = 0" and "tip = main tip" are the same predicate. Compared as OIDs
+  # because BOTH ARE ALREADY IN HAND from the ref batch — a `rev-list --count`
+  # would re-derive it at one spawn per branch, the per-branch tail this scan
+  # has repeatedly been thinned to remove.
+  #
+  # OFFLINE, AND DELIBERATELY SO. No host call is added here:
+  # `a-throttled-host-says-so` measured `plot-pr-merged.sh` answering *not
+  # merged* for three genuinely merged branches while throttled, and this
+  # reading must not inherit that failure mode.
+  #
+  # The squash path is untouched and must stay so — its mirror defect (a
+  # squash-merged branch reading `open`) is a separate plan, and a fix for one
+  # can break the other. A squash-merged branch is BEHIND main and reaches the
+  # `merged` below; a squash-merged branch whose ref was pushed back counts
+  # `ahead > 0` and never arrives here at all.
+  local _bs_tip _bs_main
+  _bs_tip=$(remote_ref_oid "$br")
+  _bs_main=$(remote_ref_oid "$MAIN")
+  if [ -n "$_bs_tip" ] && [ "$_bs_tip" = "$_bs_main" ]; then
+    # It points AT the default branch: no work of its own, and none of its own
+    # landed. `open` is what this scan already says for work not yet done, so
+    # no new state enters the vocabulary and the wave arithmetic is unchanged.
+    echo "open"; return
+  fi
   echo "merged"
 }
 
@@ -2920,8 +3269,17 @@ if [ "$next_only" != 1 ] && [ "$as_json" != 1 ]; then
 fi
 
 n_plans=0 n_waves=0 n_branches=0 n_claimed=0 n_eligible=0 n_blocked=0 n_deferred=0
+# Two BRANCH counters beside the wave ones above. `n_blocked` counts waves an
+# earlier wave holds; these count branches their `waits:` annotation holds, and
+# the footer keeps the two words apart for that reason.
+n_waiting=0 n_prereq_missing=0
 claimable=()
 plan_files=()
+# `--why-nothing`'s input: one `verdict<TAB>name:state|...` line per slice, in
+# plan order. Accumulated in the SAME loop that renders the branches, so the
+# outlook reads the verdicts a caller's `--next` just acted on rather than a
+# second derivation that could disagree with them.
+outlook_lines=""
 
 plan_idx=-1
 for plan in "${plans[@]}"; do
@@ -3038,24 +3396,65 @@ for plan in "${plans[@]}"; do
   # only safe because of that same rule: it is "-" when absent, never "". The
   # tabs inside it are replaced with spaces by the shim above, for the same
   # reason. It cannot go last; `claim` already is.
+  #
+  # `waits` — the branch a slice waits on — is a MIDDLE column under the same
+  # rule, and it is a branch name so it carries no tab of its own. It sits
+  # between `why` and the wave name, which moved the wave name to field 7: the
+  # `awk` that reads it below was updated with this line and the two must move
+  # together.
   states=""
-  while IFS=$'\t' read -r idx br deferred why wname claim; do
+  while IFS=$'\t' read -r idx br deferred why waits wname claim; do
     [ -n "$br" ] || continue
+    # "-" is the absent marker the shim writes, for the tab-collapse reason
+    # above. Normalized here so everything downstream tests emptiness.
+    [ "$waits" = "-" ] && waits=""
     if [ "$deferred" = "true" ]; then st="deferred"; else st=$(branch_state "$br"); fi
-    states+="$idx	$br	$st	$deferred	$why	$wname	$claim"$'\n'
+    # THE PREREQUISITE, AFTER THE BRANCH'S OWN STATE AND ONLY OVER TWO OF ITS
+    # WORDS. `deferred` outranks it — somebody gave the branch up, which is a
+    # decision, while waiting is a measurement — and so does any state that
+    # means work exists: `wip`, `claimed` and `merged` all say the branch was
+    # started, and overriding `merged` would stop its wave settling FOREVER,
+    # which is the blocked-on-success failure this feature is built to avoid.
+    #
+    # So the override lands exactly where the defect was: a branch that reads
+    # as unstarted, which is the population `--next` hands out.
+    if [ -n "$waits" ]; then
+      case "$st" in
+        open|unknown)
+          waits_st=$(waits_state "$waits")
+          [ -n "$waits_st" ] && st="$waits_st" ;;
+      esac
+    fi
+    # "-" GOES BACK IN, for the reason it was there in the first place: this
+    # record is re-read by two more `read` loops below, and an EMPTY middle
+    # column collapses its tab into its neighbour's and shifts every later
+    # field left. `$claim` is the only field allowed to be last and optional.
+    states+="$idx	$br	$st	$deferred	$why	${waits:--}	$wname	$claim"$'\n'
   done <<< "$wave_lines"
 
-  # Pass 2: wave verdicts. A wave is complete when none of its non-deferred
-  # branches is outstanding; eligible when all PRIOR waves are complete.
+  # Pass 2a: what each wave HOLDS — how many of its non-deferred branches have
+  # not settled. A reading, and the whole of what this script contributes to the
+  # verdict: which branches count as settled depends on `--loose` and on a host
+  # round trip, both of which are adaptation. What a wave therefore IS is the
+  # domain's, asked once for the whole plan in pass 2b.
   wave_ids=$(printf '%s' "$states" | cut -f1 | sort -un)
-  prior_ok=1
+  wave_readings=""
+  # ONE LINE PER SLICE, in the order `wave_ids` yields them — the same shape as
+  # `wave_readings` above and `wave_verdicts` below, walked by the same index.
+  # NOT an associative array: macOS ships bash 3.2, which has none, and
+  # `test/reconcile/mergequeue.test.mjs` refuses one.
+  wave_degraded_list=""
   for wid in $wave_ids; do
-    wname=$(printf '%s' "$states" | awk -F'\t' -v w="$wid" '$1==w {print $6; exit}')
-    [ "$wname" = "-" ] && wname=""
     outstanding=0
     _loose_degraded_branches=""
-    while IFS=$'\t' read -r idx br st deferred why nm claim; do
+    wave_states=""
+    while IFS=$'\t' read -r idx br st deferred why waits nm claim; do
       [ "$idx" = "$wid" ] || continue
+      # EVERY branch, including the deferred ones, and in the order the render
+      # loop below will walk them — the claimable flags come back positionally,
+      # so the two walks must agree. `outstanding` skips deferred branches; this
+      # does not, because a deferred branch still occupies a position.
+      wave_states+="${wave_states:+|}$st"
       [ "$st" = "deferred" ] && continue
       # strict (default): only a merged branch is settled.
       # loose: pushed work counts too — buys throughput, pays in rebase risk.
@@ -3075,43 +3474,42 @@ for plan in "${plans[@]}"; do
         *) outstanding=$((outstanding + 1)) ;;
       esac
     done <<< "$states"
+    wave_readings+="$outstanding	$plan_phase	$wave_states"$'\n'
+    wave_degraded_list+="$_loose_degraded_branches"$'\n'
+  done
 
-    # `eligible` IS A CLAIM ABOUT STARTABILITY, not about wave ordering alone.
-    #
-    # Measured 2026-08-27: every one-wave plan in `not-started` on the live
-    # board read `eligible`, and `plot-dispatch.sh` refused all six of them —
-    # *"plan '<slug>' is still Draft on <ref> — nothing may be dispatched."*
-    # Six of six. Both components were correct and they were answering
-    # different questions: this computed *no earlier wave blocks this one*,
-    # and the reader took it to mean *I can start this*. Those coincide only
-    # for an approved plan.
-    #
-    # THE PHASE IS ALREADY IN HAND. `$plan_phase` was parsed above for the
-    # terminal grouping, so consulting it here costs no read and no host call
-    # — the fix adds a test, not a lookup.
-    #
-    # AN ALLOWLIST OF ONE GOOD PHASE, mirroring `plot-dispatch.sh`'s own gate
-    # (`case "$gate_phase" in approved) ;;`) rather than testing for `draft`.
-    # A denylist is the blocklist-collapse shape this codebase keeps removing:
-    # `design` is documented as a phase whose work cannot yet be handed over,
-    # and `UNKNOWN`/`NONE` are unreadable answers. Under a `draft`-only test
-    # each of those would inherit the good word. The scan and the dispatcher
-    # now refuse the same set, which is the disagreement this removes.
-    #
-    # ORDERING IS STILL COMPUTED FIRST, and `complete` still outranks it: a
-    # wave whose branches have all merged IS complete whatever its plan says,
-    # because that is a statement about work that already landed, not an
-    # invitation to start any. Only the word a reader ACTS on is withheld.
-    #
-    # NOT `blocked`, deliberately. That word means *an earlier wave has not
-    # landed* — an ordering fact that resolves by merging work. This resolves
-    # by a person approving the plan. Folding both into one word would rebuild
-    # the ambiguity one level down, and `blocked by <wave> — 1 branch` is a
-    # sentence a row in this state cannot truthfully complete.
-    if [ "$outstanding" -eq 0 ]; then verdict="complete"
-    elif [ "$plan_phase" != "approved" ]; then verdict="unapproved"
-    elif [ "$prior_ok" -eq 1 ]; then verdict="eligible"
-    else verdict="blocked"; fi
+  # Pass 2b: THE DECISION, and it is not made here.
+  #
+  # `sliceVerdict` lives in `@plot-pm/domain` and this script asks it. The four
+  # words and the order they are decided in — `complete` outranking everything,
+  # approval being part of `eligible`, `unapproved` kept apart from `blocked`
+  # because they resolve differently — are all one implementation now, shared
+  # with every other component that has to agree about what may be started.
+  #
+  # ONE CALL PER PLAN, not per wave. The verdicts of a plan's waves are a FOLD:
+  # each depends on whether every wave before it is complete, so the whole
+  # ordered list is the unit the rule takes. That also keeps the cost at one
+  # process per plan on a path the board polls every five seconds.
+  #
+  # A MISSING OR SILENT ARTIFACT REFUSES. There is no shell fallback: a second
+  # implementation kept "just in case" is the duplication this adoption removes,
+  # and it would be the copy nobody tests. `plot-deliver.sh` fails the same way
+  # for the same reason.
+  wave_verdicts=$(printf '%s' "$wave_readings" \
+    | node "$script_dir/board/plot-verdicts.mjs" 2>/dev/null) \
+    || { echo "error: cannot read slice verdicts — run 'pnpm build:board'." >&2; exit 2; }
+  [ "$(printf '%s\n' "$wave_verdicts" | grep -c .)" = "$(printf '%s' "$wave_readings" | grep -c .)" ] \
+    || { echo "error: slice verdicts did not answer for every slice of $plan_base." >&2; exit 2; }
+
+  verdict_i=0
+  for wid in $wave_ids; do
+    verdict_i=$((verdict_i + 1))
+    IFS=$'\t' read -r verdict wave_claimable \
+      <<< "$(printf '%s\n' "$wave_verdicts" | sed -n "${verdict_i}p")"
+    branch_i=0
+    _loose_degraded_branches=$(printf '%s' "$wave_degraded_list" | sed -n "${verdict_i}p")
+    wname=$(printf '%s' "$states" | awk -F'\t' -v w="$wid" '$1==w {print $7; exit}')
+    [ "$wname" = "-" ] && wname=""
 
     [ "$quiet" = 1 ] || echo "  ${wname:-(unnamed)} — $verdict"
     # A degradation that says nothing is indistinguishable from a bug.
@@ -3124,12 +3522,29 @@ for plan in "${plans[@]}"; do
       echo "      (--loose degraded to strict: checks unavailable for ${_loose_degraded_branches})"
     fi
     json_branches=""
-    while IFS=$'\t' read -r idx br st deferred why nm claim; do
+    # The outlook's reading of this slice, built alongside the render. EVERY
+    # branch including the deferred ones, in the plan's order — the rule needs
+    # `deferred` to tell a branch that will never move from one that has not
+    # moved yet.
+    outlook_branches=""
+    while IFS=$'\t' read -r idx br st deferred why waits nm claim; do
       [ "$idx" = "$wid" ] || continue
+      outlook_branches+="${outlook_branches:+|}$br:$st"
       [ "$claim" = "-" ] && claim=""
       [ "$why" = "-" ] && why=""
+      [ "$waits" = "-" ] && waits=""
       n_branches=$((n_branches + 1))
       case "$st" in
+        # WHAT IT WAITS ON, NAMED. A bare `waiting` tells a reader to come back
+        # later without saying what would have to happen first, which is the
+        # whole of what this state adds over `open`.
+        waiting)  n_waiting=$((n_waiting + 1))
+                  note="waiting on $waits" ;;
+        # A PREREQUISITE NOBODY DECLARED. The sentence says the host was asked
+        # and answered, because that is what separates this from `waiting`: a
+        # host that could not be asked holds the branch at `waiting` instead.
+        blocked)  n_prereq_missing=$((n_prereq_missing + 1))
+                  note="blocked — no PR found for $waits" ;;
         # The REASON, where the plan recorded one. A bare `deferred` beside a
         # branch with no commits reads as two unrelated facts when the first is
         # the reason for the second, and the sentence that says so was already
@@ -3138,9 +3553,22 @@ for plan in "${plans[@]}"; do
         claimed)  n_claimed=$((n_claimed + 1));   note="claimed${claim:+ ($claim)}" ;;
         merged)   note="merged" ;;
         wip)      note="in progress" ;;
+        # THE HOST COULD NOT BE ASKED, so nothing is claimed about the PR. The
+        # sentence says which question went unanswered rather than naming a
+        # state, because a reader chasing `open` looks for work that was never
+        # started — the reaper's `unlanded work` made exactly that mistake about
+        # a merged branch, in a claim about CONTENT.
+        unknown)  note="unknown — PR could not be read ($HOST_VERDICT host)" ;;
         *)        note="open" ;;
       esac
-      if [ "$verdict" = "eligible" ] && [ "$st" = "open" ]; then
+      # WHETHER A WORKER MAY TAKE THIS BRANCH — the domain's answer, read
+      # positionally from the flags the same call returned. It was
+      # `[ "$verdict" = "eligible" ] && [ "$st" = "open" ]` here, a second
+      # statement of `isClaimable` sitting one loop away from the verdict it
+      # depends on. `--next` acts on this immediately by pushing a ref, so the
+      # two must not be free to disagree.
+      branch_i=$((branch_i + 1))
+      if [ "${wave_claimable:$((branch_i - 1)):1}" = "1" ]; then
         n_eligible=$((n_eligible + 1))
         claimable+=("$br")
       fi
@@ -3154,6 +3582,16 @@ for plan in "${plans[@]}"; do
         # branch is not deferred, and "" where it is deferred with nothing
         # recorded — the flag says which of those two a reader is looking at.
         json_branches+=",\"deferred_reason\":\"$(json_str "$why")\""
+        # WHAT THIS BRANCH WAITS ON, straight from the plan's `waits:`
+        # annotation. "" where the branch declares nothing, which is the answer
+        # every branch gave before this field existed.
+        #
+        # THE ANNOTATION, NOT THE VERDICT, and it is emitted whatever `state`
+        # says. A branch whose prerequisite has MERGED reports `waits_on` with
+        # its ordinary state — the declaration is still a fact about the plan,
+        # and a reader who sees a cleared dependency learns why the slice is
+        # now startable. Consumers test `state`, never the presence of this.
+        json_branches+=",\"waits_on\":\"$(json_str "$waits")\""
         json_branches+=",\"claimed\":\"$(json_str "$claim")\""
         # What this machine knows and the refs do not. Absent everywhere else:
         # `local_dirty:false` and `local_worktree:""` are what a branch checked
@@ -3338,8 +3776,13 @@ for plan in "${plans[@]}"; do
       json_waves+=",\"verdict\":\"$verdict\",\"branches\":[$json_branches]}"
     fi
 
+    outlook_lines+="$verdict	$outlook_branches"$'\n'
+
     n_waves=$((n_waves + 1))
-    [ "$verdict" = "complete" ] || prior_ok=0
+    # `prior_ok` used to be carried here — the ordering half of the verdict,
+    # threaded through the render loop. It moved with the rule: `sliceVerdicts`
+    # folds the plan's waves in order, so nothing downstream has to remember
+    # what the wave before it decided.
     [ "$verdict" = "blocked" ] && n_blocked=$((n_blocked + 1))
   done
   if [ "$as_json" = 1 ]; then
@@ -3362,7 +3805,7 @@ for plan in "${plans[@]}"; do
     # THE STREAM'S POINT: this plan is fully derived, so a consumer can render
     # it now rather than when the eighty-fourth branch resolves. Emitted as one
     # line so a reader can split on newlines without parsing incrementally, and
-    # tagged so the terminal `pulse` line cannot be mistaken for another plan.
+    # tagged so the terminal `reading` line cannot be mistaken for another plan.
     #
     # Flushed by `printf` on a line of its own: a consumer reading this stream
     # is reading it BECAUSE the whole document takes 18 s, so buffering the
@@ -3374,6 +3817,37 @@ for plan in "${plans[@]}"; do
   [ "$quiet" = 1 ] || echo
 done
 
+# --why-nothing: WHICH nothing, for a caller `--next` has just gone silent on.
+#
+# IT ANSWERS BEFORE `--next` DOES, and that ordering is the flag's whole
+# contract. `--why-nothing` sets `next_only` so it walks the same population,
+# but it must not fall into the block below: that block exits 1 on an empty
+# `claimable[]`, and a worker reading exit 1 from the flag it asked for a WORD
+# from learns nothing it did not already know. Measured 2026-09-03 on this
+# estate: `--why-nothing <slug>` printed nothing and exited 1 for every real
+# plan, because #642 shipped the parse, the accumulator and the rule and never
+# wired the emitter on this path. Only the empty-estate arm at ":2827" ever
+# answered.
+#
+# `available` IS REPORTED RATHER THAN HIDDEN. The rule reports it when a
+# claimable branch exists, which means this scan and the caller's `--next`
+# disagree — a real state (a branch landed in the seconds between the two
+# calls) and one a waiting caller should act on rather than sleep through.
+#
+# EXIT 0 EITHER WAY, INCLUDING WHEN THE RULE CANNOT BE ASKED. A silent or
+# missing artifact answers `none`, the same conservative default ":2827" takes:
+# `none` ends a wait, and a wait that cannot end is the one failure this flag
+# exists to prevent. That is the opposite of every other caller of
+# `plot-verdicts.mjs`, which refuses on a missing artifact — those callers
+# decide what may be STARTED and a wrong answer claims a branch; this one
+# decides whether a worker sleeps, and the wrong answer is the sleep.
+if [ "$why_nothing" = 1 ]; then
+  printf '%s' "$outlook_lines" \
+    | node "$script_dir/board/plot-verdicts.mjs" outlook 2>/dev/null \
+    || echo "none"
+  exit 0
+fi
+
 # --next: name ONE branch a worker may claim, or stay silent with exit 1.
 # "Nothing to start" is a normal state, not a failure — the exit code is what
 # distinguishes it from a name, so callers can branch on it without parsing.
@@ -3393,7 +3867,7 @@ fi
 # pulse re-derives everything from git.
 if [ "$log_pulse" = 1 ]; then
   stamp=$(date -u +%Y-%m-%dT%H:%MZ)
-  line="<!-- pulse: $stamp — waves=$n_waves eligible=$n_eligible claimed=$n_claimed blocked=$n_blocked deferred=$n_deferred -->"
+  line="<!-- pulse: $stamp — waves=$n_waves eligible=$n_eligible claimed=$n_claimed blocked=$n_blocked deferred=$n_deferred waiting=$n_waiting prereq_missing=$n_prereq_missing -->"
   for pf in ${plan_files[@]+"${plan_files[@]}"}; do
     real=$(cd "$(dirname "$pf")" && readlink "$(basename "$pf")" 2>/dev/null || true)
     target=$([ -n "$real" ] && echo "$(dirname "$pf")/$real" || echo "$pf")
@@ -3417,11 +3891,11 @@ fi
 if [ "$as_json" = 1 ]; then
   # --stream wraps the SAME document in one tagged line rather than emitting a
   # second, smaller one. The terminal object is what proves the scan finished:
-  # a consumer that has seen `plan` lines and no `pulse` line has a PARTIAL
+  # a consumer that has seen `plan` lines and no `reading` line has a PARTIAL
   # answer and must say so — which is the whole distinction this mode adds, and
   # the reason the end is marked rather than inferred from the pipe closing.
   # A killed scan closes the pipe too.
-  [ "$stream" = 1 ] && printf '{"kind":"pulse","pulse":'
+  [ "$stream" = 1 ] && printf '{"kind":"reading","reading":'
   # `read_ref` is the ref this document was derived from; `local_head` is the
   # checkout it was derived ON. A consumer needs both to tell "the board is
   # current" from "the board is current about an old world".
@@ -3444,8 +3918,17 @@ if [ "$as_json" = 1 ]; then
     "$(json_str "$FETCH_ERROR")" "$(json_str "$PLAN_SOURCE")" "$json_plans"
   printf '"summary":{"plans":%d,"waves":%d,"branches":%d,"claimed":%d,' \
     "$n_plans" "$n_waves" "$n_branches" "$n_claimed"
-  printf '"eligible":%d,"blocked":%d,"deferred":%d,"merge_detect":"%s"}}' \
-    "$n_eligible" "$n_blocked" "$n_deferred" "$MERGE_DETECT"
+  # `host` is the EVIDENCE field beside merge_detect, and it is the one that
+  # says whether merge_detect can be believed. Rendered for the machine here
+  # and in the footer for a human; the board reads this rather than parsing
+  # the prose, the rule every other field follows.
+  # `waiting` and `prereq_missing` count BRANCHES, where `blocked` above counts
+  # WAVES. Two vocabularies share the word `blocked` and the footer must not:
+  # a consumer adding the three would double-count nothing, because no branch
+  # is in both and no wave is in either.
+  printf '"eligible":%d,"blocked":%d,"deferred":%d,"waiting":%d,"prereq_missing":%d,"merge_detect":"%s","host":"%s"}}' \
+    "$n_eligible" "$n_blocked" "$n_deferred" "$n_waiting" "$n_prereq_missing" \
+    "$MERGE_DETECT" "$HOST_VERDICT"
   [ "$stream" = 1 ] && printf '}'
   printf '\n'
   exit 0
@@ -3459,6 +3942,35 @@ if [ "$MERGE_SCAN_TRUNCATED" = 1 ]; then
   echo "  note: merge scan hit its limit of $MERGE_SCAN_LIMIT — older merges were not"
   echo "        examined; a branch merged before that point may still read as open."
 fi
+# A HOST THAT COULD NOT BE ASKED SAYS SO, and says what to do about it.
+#
+# `pr-list` is ONE GraphQL call in place of ~186 REST calls — a deliberate and
+# good trade whose consequence is that throttling takes out EVERY PR answer at
+# once rather than degrading row by row. So the whole fleet reads unmerged,
+# every wave stays blocked, and the board shows a busy estate with nothing
+# eligible: indistinguishable from work genuinely in flight, which is why this
+# has to be stated rather than left for a reader to infer from a quiet report.
+#
+# THE THREE WORDS GET DIFFERENT ADVICE because they need different responses.
+# A spent quota returns at the reset, minutes away; a secondary limit clears in
+# seconds and is fixed by running fewer calls at once; an outage clears when
+# somebody looks at it.
+if [ "$HOST_VERDICT" = throttled ]; then
+  echo "  note: the git host's rate limit was spent, so no PR could be read. Every"
+  echo "        branch below reads from local evidence alone — a merged branch whose"
+  echo "        ref was deleted reads 'unknown', never 'open', and none was offered"
+  echo "        to --next. The budget refills on a clock; re-run in a few minutes."
+elif [ "$HOST_VERDICT" = secondary ]; then
+  echo "  note: the git host refused a burst, not a spent budget, so no PR could be"
+  echo "        read. Every branch below reads from local evidence alone and none"
+  echo "        was offered to --next. This clears in seconds — re-run shortly, and"
+  echo "        run fewer scans at once rather than waiting for a reset."
+elif [ "$HOST_VERDICT" = failed ]; then
+  echo "  note: the git host could not be reached, so no PR could be read. Every"
+  echo "        branch below reads from local evidence alone, and a branch whose"
+  echo "        PR is unknown reads 'unknown' rather than 'open'. This is not a"
+  echo "        rate limit — waiting will not clear it; check the host and auth."
+fi
 # A STALE PULSE SAYS SO. The fetch used to fail silently, which made a scan of
 # hour-old refs read exactly like a scan of current ones — the same
 # over-confidence, one layer up, that this plan fixes in the plan list.
@@ -3493,4 +4005,4 @@ if [ "$PLAN_SOURCE" != "ref" ]; then
   echo "        checkout instead, so the list is only as current as your last pull."
 fi
 echo "Pulse complete. This report is derived — nothing was changed."
-echo "summary: plans=$n_plans waves=$n_waves branches=$n_branches claimed=$n_claimed eligible=$n_eligible blocked=$n_blocked deferred=$n_deferred merge_detect=$MERGE_DETECT main=$MAIN"
+echo "summary: plans=$n_plans waves=$n_waves branches=$n_branches claimed=$n_claimed eligible=$n_eligible blocked=$n_blocked deferred=$n_deferred waiting=$n_waiting prereq_missing=$n_prereq_missing merge_detect=$MERGE_DETECT host=$HOST_VERDICT main=$MAIN"