@plot-pm/board 0.10.0 → 0.12.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
@@ -123,12 +177,29 @@
 # crashed pulse costs nothing — the next pulse re-derives the truth. Nothing
 # here creates a branch, pushes a ref, or starts a worker.
 #
-# ONE exception to "writes nothing": --log-pulse appends a pulse line to each
-# reported plan (see below). That is a LOG, not state — deleting the whole log
-# changes no behaviour, because the next run re-derives everything. The flag
-# defaults OFF precisely so internal callers (plot-implement, plot-dispatch,
-# which invoke --next) can never amend a plan as a side effect of asking what
-# to work on; /plot-fleet, the human-facing command, passes it every run.
+# TWO exceptions to "writes nothing", and NEITHER IS STATE. The test both pass
+# is the same one: delete what they wrote and no behaviour changes, because the
+# next run re-derives everything.
+#
+# 1. --log-pulse appends a pulse line to each reported plan (see below). That is
+#    a LOG. The flag defaults OFF precisely so internal callers (plot-implement,
+#    plot-dispatch, which invoke --next) can never amend a plan as a side effect
+#    of asking what to work on; /plot-fleet, the human-facing command, passes it
+#    every run.
+#
+# 2. `.plot/state/last-pulse.json` — the bridge, written by `write_bridge` on
+#    the success path of `--stream` (what the board spawns) and `--log-pulse`
+#    (what /plot-pulse passes). Those are the two callers that produce a pulse
+#    for somebody to READ; plain `--json` is a query and records nothing. That
+#    is a CACHE WITH AN EXPIRY: `pulse-bridge.ts` discards it after 15 minutes
+#    and on a version mismatch, so it can only ever be a shortcut to an answer
+#    this script re-derives anyway. It is machine-local and gitignored.
+#
+#    Added 2026-09-06. The board wrote this file and the scan did not, so a
+#    repository with no board had nothing to diff against and every pulse read
+#    as the first one — while `DESIGN-process.md` §1 requires the fleet to work
+#    with no board at all. The component that PRODUCES a pulse is the one that
+#    records it.
 #
 # Wave eligibility (the one rule this script encodes):
 #   A wave is ELIGIBLE when every non-deferred branch in every PRIOR wave is
@@ -159,20 +230,52 @@ 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
+# Whether the JSON document is ASSEMBLED, which is not the same question as
+# whether it is PRINTED. `--json`/`--stream` need it to print; `--log-pulse`
+# needs it to write the bridge and prints prose. Measured 2026-09-06 on this
+# estate: assembling it costs 14.7 s against 5.9 s for prose alone, because the
+# branch objects carry `merge-tree` conflict sets. So the two meanings are
+# separated rather than folded, and a plain `/plot-fleet-scan.sh` pays neither.
+build_doc=0
+# Whether this run RECORDS the pulse it produced — `.plot/state/last-pulse.json`.
+# A third question again: `--json` assembles a document and records nothing,
+# because it is a query. Only the two callers that produce a pulse for somebody
+# to read set this — `--stream` (the board) and `--log-pulse` (/plot-pulse).
+record=0
 stream=0
 slug=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --no-fetch|--offline) do_fetch=0 ;;
     --loose) loose=1 ;;
-    --log-pulse) log_pulse=1 ;;
+    # `--log-pulse` ALSO ASSEMBLES THE DOCUMENT, because this is the flag that
+    # means *this pulse records itself*. It already appends a line to each plan;
+    # it now also writes `.plot/state/last-pulse.json`, so `/plot-pulse` in a
+    # repository with no board accumulates the history a delta needs. Without
+    # that, every pulse on a boardless repo is a first one forever.
+    --log-pulse) log_pulse=1; build_doc=1; record=1 ;;
     --next) next_only=1 ;;
     --list-eligible) next_only=1; list_all=1 ;;
-    --json) as_json=1 ;;
-    --stream) as_json=1; stream=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` ASSEMBLES BUT DOES NOT RECORD, and the two flags differ here for
+    # a reason. `--stream` is what the BOARD spawns (`fleet.ts:2694`) and
+    # `--log-pulse` is what `/plot-pulse` passes: both produce a pulse somebody
+    # is reading, so both record one. Plain `--json` is a machine-readable
+    # QUERY — `--next`'s neighbours ask it to find out what to work on — and a
+    # query that left a file behind would make the scan write on a path no
+    # caller asked to record. Two reconcile tests assert exactly that and
+    # caught this: `conflicts: the scan writes NOTHING` and `fleet: scan is
+    # read-only`, both of which drive `--json`.
+    --json) as_json=1; build_doc=1 ;;
+    --stream) as_json=1; stream=1; build_doc=1; record=1 ;;
     -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
     *) slug="$1" ;;
   esac
@@ -188,11 +291,13 @@ PREFIX_RE=$(cfg "Branch prefixes" "idea/, feature/, bug/, docs/, infra/" \
   | tr -d ' ' | tr ',' '\n' | sed 's#/$##' | grep -v '^$' | paste -sd'|' -)
 [ -n "$PREFIX_RE" ] || PREFIX_RE="idea|feature|bug|docs|infra"
 
+# `default_branch` repairs an unresolvable origin/HEAD before answering. The
+# scan derives every branch's state from `origin/<main>`, so a symref naming a
+# branch that does not exist makes every one of them unreadable at once.
+# shellcheck source=plot-default-branch.sh
+. "$script_dir/plot-default-branch.sh"
 MAIN=$(cfg "Main branch")
-if [ -z "$MAIN" ]; then
-  MAIN=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')
-fi
-[ -n "$MAIN" ] || MAIN="main"
+[ -n "$MAIN" ] || MAIN=$(default_branch)
 
 # A FAILED FETCH IS A FACT, not a shrug. The old line was
 # `git fetch ... 2>/dev/null` with its status discarded: a GitHub 503, a
@@ -390,8 +495,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 +618,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 +659,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 —
@@ -844,8 +1089,16 @@ terminal_learn() { # $1=branch $2=state
 # branch that is live — in flight, claimed, or with work on the floor — never
 # arrives here and therefore cannot be cached however the cache is filled. The
 # invariant is structural rather than a check that could be forgotten.
+#
+# SETS `_merged_by_host_state` TO THE WORD IT DECIDED ON, and that is what the
+# readings carry. The boolean is still the answer to this function's own
+# question; the word is what `branch_readings` reports, because the rule needs
+# to tell `CLOSED` from `NONE` from `-` and a yes/no cannot. Set before every
+# return, so a caller reading it never sees the previous branch's answer.
+_merged_by_host_state='-'
 merged_by_host() { # $1=branch → 0 when the host reports its PR MERGED
   local st
+  _merged_by_host_state='-'
   # Git has already been consulted to get here (no ref) and `terminal_cached`
   # asks it again about the plan and the tip. Only the round trip is skipped.
   if st=$(terminal_cached "$1"); then
@@ -858,11 +1111,13 @@ merged_by_host() { # $1=branch → 0 when the host reports its PR MERGED
     # It is re-derived, not merely echoed: reaching here means git was asked
     # again this pass and still agrees — no ref, same plan, same tip.
     terminal_learn "$1" "$st"
+    _merged_by_host_state="$st"
     [ "$st" = "MERGED" ]
     return
   fi
   st=$(host_pr_state "$1" --ask)
   terminal_learn "$1" "$st"
+  _merged_by_host_state="$st"
   [ "$st" = "MERGED" ]
 }
 
@@ -883,6 +1138,52 @@ 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.
+#
+# WHAT THE HOST SAID, AND NOT WHAT IT MEANS. This function answered
+# `waiting` / `blocked` / `""` until the derivation moved: the three answers and
+# the reason `NONE` is the only one that means `blocked` are `waitVerdict` in
+# `packages/domain/src/rules/branch-state.ts`, with a test per case. What stays
+# here is the READING and the cost argument above it, which is a fact about
+# this script's host budget rather than about what a wait means.
+#
+# `--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.
+waits_pr_state() { # $1=prerequisite branch → OPEN|MERGED|CLOSED|NONE|-
+  host_pr_state "$1" --ask
+}
+
 # Modification time of a path, in epoch seconds, following symlinks — or "" when
 # it cannot be read.
 #
@@ -2401,9 +2702,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 +2924,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 +2950,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
@@ -2733,8 +3045,39 @@ EOF
   echo "$total $n"
 }
 
-branch_state() {
-  local br="$1"
+# WHAT WAS READ OF ONE BRANCH — ten tab-separated fields, and no decision.
+#
+# `branch_state()` UNTIL THIS SLICE, and every line of git archaeology below is
+# its own, unchanged. What went is the `if` chain that merged these readings
+# into a state word: that lives in `@plot-pm/domain`'s `branchState`, which the
+# caller asks once per plan through `plot-branch-state.mjs`. The script gathers;
+# the rule decides.
+#
+# THE REF CHECK STAYS IN FRONT, and it still does its job here. It is no longer
+# a `return`, so the ordering is preserved a different way: `mergeSubjectFound`
+# is READ ONLY where there is no ref, and reported `false` otherwise. See the
+# comment on that reading below — it is the same argument the returns carried.
+#
+# `-` IS THE ABSENT MARKER, per the field-order rule the caller documents: a
+# run of tabs collapses into one separator under `read`, so no field is ever
+# empty. Nothing here is optional, so nothing can shift.
+#
+# EIGHT FIELDS, NOT TEN. The two the plan states — the prerequisite's name and
+# what the host said about it — are appended by the caller, because reading the
+# second costs a host round trip and the scan spends it only where it could
+# change the answer. The rule reports which states those are; see the caller.
+#
+# THE DEFAULT BRANCH'S TIP IS READ ONCE PER RUN, not once per branch. It does
+# not move while the scan runs — every fact below is derived from the ref batch
+# taken at the start — and `remote_ref_oid` forks an `awk`, so asking per branch
+# would put one process per branch back on the 5 s pulse path. That is the
+# per-branch tail this script has repeatedly been thinned to remove.
+MAIN_TIP=$(remote_ref_oid "$MAIN")
+[ -n "$MAIN_TIP" ] || MAIN_TIP="-"
+
+branch_readings() { # $1=branch $2=deferred → eight tab-separated readings
+  local br="$1" _bs_deferred="$2" _bs_subject=false _bs_ahead=0 _bs_real=0 _bs_tip
+  local _bs_main="$MAIN_TIP"
   # THE REF CHECK STAYS IN FRONT. DO NOT HOIST THE MERGE LOOKUP ABOVE IT.
   #
   # A branch name can be reused: merge `bug/flaky`, delete it, then recreate it
@@ -2745,9 +3088,16 @@ branch_state() {
   #
   # The merge lookup is safe only BY PLACEMENT — it lives in the no-ref arm,
   # and a recreated branch has a ref, so it never reaches the lookup and takes
-  # the ancestry path below instead. Moving the lookup to the top reads like a
-  # cheap early answer and would silently report in-flight work as `merged`,
-  # opening the next wave on it. A test in fleet.test.mjs pins this ordering.
+  # the ancestry path below instead. Moving the lookup out of this `if` reads
+  # like a cheap early answer and would silently report in-flight work as
+  # `merged`, opening the next wave on it. A test in fleet.test.mjs pins this
+  # ordering, and `branch-state.test.ts` pins what the rule makes of it.
+  #
+  # THE PLACEMENT IS NOW A READING RATHER THAN A RETURN, and it holds the same
+  # way: a branch WITH a ref reports `mergeSubjectFound=false` whatever main
+  # says about its name, so the stale subject never reaches the rule at all.
+  # The rule's own comment says it may not be consulted before the ref check;
+  # this is the half of that contract the caller owes.
   if ! remote_ref_exists "$br"; then
     # No ref carries two meanings and this used to answer `open` for both: a
     # branch never started, and a branch merged with its ref deleted at merge.
@@ -2757,16 +3107,69 @@ branch_state() {
     # `merged` is already the state that settles a wave, so the arithmetic does
     # not change and no new state enters the vocabulary. Where no evidence
     # exists — squash merges, a hand-rewritten subject, a branch genuinely
-    # never started — today's `open` stands. The fix may only move a branch
-    # from `open` to `merged`, and only on positive evidence.
-    merged_by_subject "$br" && { echo "merged"; return; }
+    # never started — today's `open` stands. The evidence may only move a branch
+    # from `open` to `merged`, and only when it is positive.
+    merged_by_subject "$br" && _bs_subject=true
     # No merge commit names it — which is the ordinary case under a squash
     # merge, not an exotic one. The local walk is now out of evidence, so the
     # host is asked. It may only ever move this branch from `open` to `merged`:
-    # 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; }
-    echo "open"; return
+    # a miss, a CLOSED PR, or a host that cannot answer all leave the reading
+    # as it was, exactly as before this call existed.
+    #
+    # ASKED ONLY HERE, and that bound is the whole of PR #216: this arm is
+    # reached only for a branch with NO REF, so the per-branch host cost is
+    # bounded by ABSENT branches rather than by all of them. Hoisting the call
+    # out of this `if` to "gather uniformly" would put 22 round trips back into
+    # every scan on this repo. The reading is `-` for every branch that has a
+    # ref, and the rule never reaches its PR arm for one that does.
+    #
+    # THE TERMINAL CACHE WRAPS IT, and stays here rather than moving inward.
+    # The cache is about how OFTEN a question is asked; the rule is about what
+    # the answer MEANS. `merged_by_host` consults it, so a terminal branch is
+    # asked once and its answer is reused across pulses — 26 of 54 branches on
+    # this estate, measured 2026-08-19.
+    #
+    # THE WORD, NOT THE BOOLEAN. `merged_by_host` answers its own yes/no and
+    # leaves the state word it decided on in `_merged_by_host_state`, which is
+    # what travels: the rule tells `CLOSED` from `NONE` from `-`, and a boolean
+    # cannot. `|| true` because a not-merged answer is an ordinary reading and
+    # `set -e` must not read it as a failure.
+    merged_by_host "$br" || true
+    # `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 above and not this reading.
+    #
+    # THE THREE WORDS TRAVEL AS THEMSELVES. `HOST_VERDICT` is reported rather
+    # than collapsed into a boolean, so the rule keeps `unasked` apart from
+    # `failed` — the distinction the whole readings shape exists for.
+    printf '%s\t-\t%s\t%s\t%s\t%s\t0\t0' \
+      "$_bs_deferred" "$_bs_main" "$_bs_subject" "$HOST_VERDICT" "$_merged_by_host_state"
+    return
   fi
   # A CLAIM is a branch whose only commits beyond main are claim commits —
   # empty markers a dispatcher pushed to take the work. They must be real
@@ -2778,65 +3181,115 @@ branch_state() {
   # already computing and discarding, at one extra spawn per branch.
   local _bs_counts
   _bs_counts=$(real_commits_beyond_main "$br")
-  ahead=${_bs_counts%% *}
-  real=${_bs_counts##* }
-  if [ "${ahead:-0}" -gt 0 ]; then
-    [ "${real:-0}" = "0" ] && { echo "claimed"; return; }
-    # Real work that main does not yet contain: `wip`, and ONLY `wip`.
-    #
-    # This arm once asked `merge-base --is-ancestor origin/$br origin/$MAIN`
-    # here — "has the work already landed?" — and returned `merged` when it did.
-    # That question was already answered by the `ahead` count above it and could
-    # never fire: `ahead > 0` means `$br` carries at least one commit unreachable
-    # from `$MAIN`, and a branch with such a commit CANNOT be an ancestor of
-    # `$MAIN`, so `--is-ancestor` was false on every branch that reached it. It
-    # was one git spawn per `wip` branch spent to re-derive a fact already in
-    # hand — the per-branch tail this plan set out to thin — and its `merged`
-    # was dead code that changed no verdict.
-    #
-    # The landed-work case is not lost; it is answered ONE LEVEL UP. A branch
-    # whose commits are all in `$MAIN` counts `ahead = 0` and falls through to
-    # the `merged` below, and a merge that deleted the ref never reaches here at
-    # all (the no-ref arm returns first). If a future change makes `ahead`
-    # something other than "commits `$MAIN` lacks", THIS is the invariant that
-    # would break — the ancestry must move back, not be missed.
-    #
-    # A RESURRECTED REF BREAKS THE PREMISE ABOVE, and the join already knows.
-    # The reasoning "a merge that deleted the ref never reaches here" holds only
-    # while the ref STAYS deleted. `delete_branch_on_merge` is on, so the host
-    # removes it — and a worktree that still holds the branch can push it back
-    # afterwards, which a fleet does routinely. The ref then exists again while
-    # the work is on `$MAIN` under a DIFFERENT commit, because a squash merge
-    # rewrites it: `ahead > 0` (the pre-squash commits are unreachable from
-    # `$MAIN`), `real > 0` (they are real work), and this arm calls finished
-    # work `wip`.
-    #
-    # Measured 2026-08-23: `bug/done-holds-finished-plans-only`, PR #356 merged,
-    # read `wip` for three hours. Its wave reported "3 merged, the rest not yet"
-    # over four merged branches and never completed, so the plan sat in
-    # Development with nothing left to do.
-    #
-    # `wip` is the WORST of the wrong answers, which is why this earns a check
-    # rather than a note: it means *an agent is working here*, so a leftover
-    # worktree reads as an occupied desk and the row asks a reader to wait for
-    # something that finished.
-    #
-    # FREE, and that is what licenses it HERE. The state comes from the cache
-    # `prefill_pr_states` already filled from ONE repo-wide `pr-list`, so this
-    # adds no host call — asking per branch on this arm would put 22 calls back
-    # into every scan on this repo and undo the change that removed them. Where
-    # the list did not arrive the cache is empty, `host_pr_state` answers `-`,
-    # and the local walk decides exactly as it does today.
-    #
-    # ONLY `MERGED` MAY OVERRIDE the walk, and only toward `merged`. `OPEN`
-    # means a PR exists for work still in flight — which is what `wip` already
-    # says — and `CLOSED` or `NONE` are not evidence that anything landed.
-    if [ "$(host_pr_state "$br")" = MERGED ]; then echo "merged"; return; fi
-    echo "wip"; return
-  fi
-  # Nothing of its own. NOT a claim: that shape is indistinguishable from
+  _bs_ahead=${_bs_counts%% *}
+  _bs_real=${_bs_counts##* }
+  # Real work that main does not yet contain is `wip`, and ONLY `wip` — the
+  # rule says so; this reading is what lets it.
+  #
+  # This arm once asked `merge-base --is-ancestor origin/$br origin/$MAIN`
+  # here — "has the work already landed?" — and returned `merged` when it did.
+  # That question was already answered by the `ahead` count above it and could
+  # never fire: `ahead > 0` means `$br` carries at least one commit unreachable
+  # from `$MAIN`, and a branch with such a commit CANNOT be an ancestor of
+  # `$MAIN`, so `--is-ancestor` was false on every branch that reached it. It
+  # was one git spawn per `wip` branch spent to re-derive a fact already in
+  # hand — the per-branch tail this plan set out to thin — and its `merged`
+  # was dead code that changed no verdict.
+  #
+  # The landed-work case is not lost; it is answered by the TIP COMPARISON. A
+  # branch whose commits are all in `$MAIN` counts `ahead = 0`, and a merge that
+  # deleted the ref takes the no-ref arm above. If a future change makes `ahead`
+  # something other than "commits `$MAIN` lacks", THAT is the invariant that
+  # would break — the ancestry must move back, not be missed.
+  #
+  # A RESURRECTED REF BREAKS THE PREMISE ABOVE, and the host is what closes it.
+  # The reasoning "a merge that deleted the ref never reaches here" holds only
+  # while the ref STAYS deleted. `delete_branch_on_merge` is on, so the host
+  # removes it — and a worktree that still holds the branch can push it back
+  # afterwards, which a fleet does routinely. The ref then exists again while
+  # the work is on `$MAIN` under a DIFFERENT commit, because a squash merge
+  # rewrites it: `ahead > 0`, `real > 0`, and the walk alone would call finished
+  # work `wip`.
+  #
+  # Measured 2026-08-23: `bug/done-holds-finished-plans-only`, PR #356 merged,
+  # read `wip` for three hours. Its wave reported "3 merged, the rest not yet"
+  # over four merged branches and never completed, so the plan sat in
+  # Development with nothing left to do.
+  #
+  # `wip` is the WORST of the wrong answers, which is why this earns a reading
+  # rather than a note: it means *an agent is working here*, so a leftover
+  # worktree reads as an occupied desk and the row asks a reader to wait for
+  # something that finished.
+  #
+  # FREE, and that is what licenses reading it for EVERY branch with a ref. The
+  # state comes from the cache `prefill_pr_states` already filled from ONE
+  # repo-wide `pr-list`, so this adds no host call — no `--ask` here, which is
+  # what keeps the 22 round trips out. Where the list did not arrive the cache
+  # is empty, `host_pr_state` answers `-`, and the local walk decides exactly as
+  # it does today.
+  #
+  # ONLY `MERGED` MAY OVERRIDE the walk, and only toward `merged` — the rule's
+  # business, not this function's. `OPEN` means a PR exists for work still in
+  # flight, and `CLOSED` or `NONE` are not evidence that anything landed.
+  #
+  # Nothing of its own is NOT a claim: that shape is indistinguishable from
   # merged work, which is exactly why claims carry a commit.
-  echo "merged"
+  #
+  # 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 that 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, and it is why BOTH TIPS are
+  # reported rather than a verdict about them. 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 `--ask` 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 its tips
+  # differ; a squash-merged branch whose ref was pushed back counts `ahead > 0`.
+  _bs_tip=$(remote_ref_oid "$br")
+  [ -n "$_bs_tip" ] || _bs_tip="-"
+  printf '%s\t%s\t%s\tfalse\t%s\t%s\t%s\t%s' \
+    "$_bs_deferred" "$_bs_tip" "$_bs_main" "$HOST_VERDICT" "$(host_pr_state "$br")" \
+    "${_bs_ahead:-0}" "${_bs_real:-0}"
+}
+
+# THE RULE, ASKED ONCE PER PLAN. `branchState` lives in `@plot-pm/domain` and
+# this is how the scan reaches it: readings in, one `state<TAB>needs` line per
+# branch out, in the order they were given.
+#
+# A MISSING OR SILENT ARTIFACT REFUSES, exactly as the verdicts call does.
+# 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.
+ask_branch_states() { # stdin=readings → one `state<TAB>needs` line per branch
+  node "$script_dir/board/plot-branch-state.mjs" 2>/dev/null \
+    || { echo "error: cannot read branch states — run 'pnpm build:board'." >&2; exit 2; }
 }
 
 # Prose is suppressed by BOTH alternate output modes. --json accumulates the
@@ -2920,8 +3373,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 +3500,141 @@ 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.
-  states=""
-  while IFS=$'\t' read -r idx br deferred why wname claim; do
+  #
+  # `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.
+  # PASS 1a: THE READINGS. Every branch of this plan, gathered and not judged.
+  #
+  # `branch_readings` is the git archaeology that used to end in an `if` chain.
+  # It now ends in eight tab-separated readings, and the two the plan states —
+  # the prerequisite's name and what the host said about it — are appended here.
+  #
+  # THE PREREQUISITE'S PR STATE IS NOT READ YET, and `?` says so. `-` is taken:
+  # `host_pr_state` answers it for a host that could not be reached, and the
+  # rule reads that as `unreadable` and answers `waiting`, because silence is
+  # not evidence in either direction. The two were one marker until CI ran the
+  # corpus with no token, where every prerequisite answers `-` and every waiting
+  # branch read `open`. Reading it
+  # costs a host round trip (`waits_pr_state` passes `--ask`, because a delivered
+  # prerequisite's ref is gone and only its PR outlives it), and the scan spends
+  # that only where the answer could change the branch's state. Which states
+  # those are IS the precedence, so the rule reports it rather than this loop
+  # deciding it — see pass 1c.
+  readings=""
+  order=""
+  while IFS=$'\t' read -r idx br deferred why waits wname claim; do
     [ -n "$br" ] || continue
-    if [ "$deferred" = "true" ]; then st="deferred"; else st=$(branch_state "$br"); fi
-    states+="$idx	$br	$st	$deferred	$why	$wname	$claim"$'\n'
+    # "-" is the absent marker the shim writes, for the tab-collapse reason
+    # above. Normalized here so everything downstream tests emptiness.
+    [ "$waits" = "-" ] && waits=""
+    readings+="$(branch_readings "$br" "$deferred")	${waits:--}	?"$'\n'
+    order+="$idx	$br	$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 1b: THE DECISION, and it is not made here.
+  #
+  # `branchState` lives in `@plot-pm/domain` and this script asks it. The eight
+  # words and the precedence that merges them — a plan's `deferred:` over
+  # everything git says, the ref check before the merge lookup, a prerequisite
+  # over `open` and `unknown` and nothing else — are one implementation now,
+  # with a test per case, shared with every component that has to agree about
+  # what a branch is.
+  #
+  # ONE CALL PER PLAN, not per branch, for the reason pass 2b gives: the board
+  # polls this scan every five seconds against ~40 plans, and a process per
+  # branch is the per-branch tail this script has repeatedly been thinned to
+  # remove.
+  #
+  # A MISSING OR SILENT ARTIFACT REFUSES, exactly as the verdicts call does.
+  # 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.
+  branch_answers=$(printf '%s' "$readings" | ask_branch_states)
+  [ "$(printf '%s\n' "$branch_answers" | grep -c .)" = "$(printf '%s' "$readings" | grep -c .)" ] \
+    || { echo "error: branch states did not answer for every branch of $plan_base." >&2; exit 2; }
+
+  # PASS 1c: THE PREREQUISITES THE RULE ASKED FOR, and only those.
+  #
+  # The second column of each answer is the rule's own
+  # `REPLACEABLE_BY_PREREQUISITE` — `1` where this branch names a prerequisite
+  # whose state has not been read and where reading it could change the answer.
+  # `deferred` outranks it, and so does any state meaning work exists: `wip`,
+  # `claimed` and `merged` all say the branch was started, and overriding
+  # `merged` would stop its wave settling FOREVER. That reasoning now sits in
+  # `branch-state.ts` with a test per case; this loop only spends the calls it
+  # is told to.
+  #
+  # SO THE SECOND ASK IS PAID ONLY WHEN SOMETHING IS FLAGGED, and the bound is
+  # the flagged branches rather than the annotated ones: a `waits:` branch that
+  # already reads `wip`, `claimed`, `merged` or `deferred` costs nothing.
+  refill=""
+  needs_refill=0
+  answer_i=0
+  while IFS= read -r rd_line; do
+    [ -n "$rd_line" ] || continue
+    answer_i=$((answer_i + 1))
+    IFS=$'\t' read -r _st needs \
+      <<< "$(printf '%s\n' "$branch_answers" | sed -n "${answer_i}p")"
+    waits_br=$(printf '%s' "$rd_line" | cut -f9)
+    if [ "$needs" = "1" ] && [ "$waits_br" != "-" ]; then
+      needs_refill=1
+      # `--ask` because the prerequisite is precisely the branch the repo-wide
+      # list may legitimately omit: its plan may be delivered and its ref gone.
+      # `host_pr_state`'s run cache keeps this at one call per prerequisite per
+      # run, never one per pass.
+      refill+="$(printf '%s' "$rd_line" | cut -f1-9)	$(waits_pr_state "$waits_br")"$'\n'
+    else
+      refill+="$rd_line"$'\n'
+    fi
+  done <<< "$readings"
+
+  if [ "$needs_refill" = 1 ]; then
+    branch_answers=$(printf '%s' "$refill" | ask_branch_states)
+    [ "$(printf '%s\n' "$branch_answers" | grep -c .)" = "$(printf '%s' "$refill" | grep -c .)" ] \
+      || { echo "error: branch states did not answer for every branch of $plan_base." >&2; exit 2; }
+  fi
+
+  # PASS 1d: the record every loop below reads, with the decided state in it.
+  #
+  # "-" 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=""
+  answer_i=0
+  while IFS=$'\t' read -r idx br deferred why waits wname claim; do
+    [ -n "$br" ] || continue
+    answer_i=$((answer_i + 1))
+    st=$(printf '%s\n' "$branch_answers" | sed -n "${answer_i}p" | cut -f1)
+    states+="$idx	$br	$st	$deferred	$why	$waits	$wname	$claim"$'\n'
+  done <<< "$order"
+
+  # 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 +3654,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 +3702,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,14 +3733,27 @@ 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
       [ "$quiet" = 1 ] || echo "      $br — $note"
-      if [ "$as_json" = 1 ]; then
+      if [ "$build_doc" = 1 ]; then
         # The INTERNAL state ($st), never the prose label ($note): the board
         # must not parse a string that exists for humans to read.
         json_branches+="${json_branches:+,}{\"branch\":\"$(json_str "$br")\""
@@ -3154,6 +3762,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
@@ -3333,16 +3951,21 @@ for plan in "${plans[@]}"; do
       fi
     done <<< "$states"
 
-    if [ "$as_json" = 1 ]; then
+    if [ "$build_doc" = 1 ]; then
       json_waves+="${json_waves:+,}{\"name\":\"$(json_str "$wname")\""
       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
+  if [ "$build_doc" = 1 ]; then
     # ONE composition, two destinations — the property that makes --stream and
     # --json say the same thing rather than agreeing by inspection. A second
     # `printf` shaped like this one would be a second implementation of the
@@ -3362,7 +3985,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 +3997,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 +4047,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")
@@ -3409,28 +4063,123 @@ if [ "$log_pulse" = 1 ]; then
   done
 fi
 
-# --json: the same derivation as the prose above, rendered for machines. It is
-# an OUTPUT MODE and nothing more — it composes with --offline/--no-fetch/
-# --loose rather than implying any of them, so the board's data depends on what
-# it asked for, not on how it asked. --next wins over it (handled above): that
-# is a different question with a one-line answer.
-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
-  # 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":'
+# THE PULSE RECORDS ITSELF — `.plot/state/last-pulse.json`, the bridge.
+#
+# WHY THE SCAN AND NOT THE BOARD. `fleet.ts:2804` was the ONLY writer until
+# 2026-09-06, and this script named the file zero times — so `/plot-pulse` in a
+# repository with no board had nothing to diff against, and every pulse was a
+# first one forever. `DESIGN-process.md` §1 requires the fleet to work with no
+# board at all. The scan produces the pulse; the component that produces one
+# records it. The board's write is not removed and becomes redundant: the board
+# spawns THIS script, so a scan that writes the bridge writes it on the board's
+# path too, from inside the same run.
+#
+# INSIDE THE SUCCESS PATH, WHICH IS THE PROPERTY THAT HAD TO SURVIVE THE MOVE.
+# `fleet.ts:2800`: *"A scan that failed must not overwrite the last good answer
+# — the only thing standing between a `--watch` restart and an empty board."*
+# So this is called where the scan has finished deriving and is about to say so,
+# never from a trap and never at exit. A killed scan leaves the previous file
+# whole.
+#
+# THE FORMAT IS `pulse-bridge.ts`'s AND EVERY FIELD HERE IS ITS REQUIREMENT.
+# `version` must equal `BRIDGE_VERSION` or `:193` returns null and the board
+# renders an empty page with no error — a silent failure, which is why the
+# board's own test reads a file this script wrote rather than one a fixture
+# invented. `at` is epoch MILLISECONDS and is checked against
+# `BRIDGE_MAX_AGE_MS` (15 min), and a file from the future is rejected outright
+# rather than clamped, so the clock must be the same one the board reads.
+#
+# THE FOUR MAPS ARE EMPTY AND THAT IS HONEST. `ages`, `approvedAt` and
+# `ideaPlans` are computed by the board on its own timers, and `branchUrlBase`
+# comes from its settings; the scan knows none of them. `readBridge` rebuilds
+# each with `toMap`, which yields an empty Map for anything it cannot use, and
+# `branchUrlBase` falls back to `''`. So a scan-written bridge serves the rows,
+# the verdicts and the counts, with unknown ages and no branch links — degraded
+# in the direction the board already handles, and overwritten by the board's own
+# richer write seconds later on the refresh it always issues.
+#
+# TEMP FILE PLUS RENAME, carrying the pid, exactly as `writeBridge` does and for
+# the same reason: `rename` is atomic within a filesystem, so a board reading
+# while this writes sees the old file whole or the new file whole. The pid is in
+# the temp name because two scans on one repo — routine here — must not collide
+# on one temp file and hand the reader the torn payload the rename exists to
+# prevent.
+#
+# EVERY FAILURE IS SWALLOWED, the rule `writeBridge` states: a read-only
+# checkout, a full disk, a `.plot` nobody may write to. None of that is a reason
+# for a pulse to fail, and the cost of the miss is exactly the behaviour before
+# this existed.
+#
+# IT IS A CACHE WITH AN EXPIRY, NEVER A RECORD. Deleting it changes no
+# behaviour, because the next pulse re-derives everything — which is what keeps
+# this inside the script's stateless design rather than beside it.
+# The previous pulse's document, read BEFORE `write_bridge` replaces it.
+#
+# EMPTY MEANS NO FILE, and that is a fact about the FILE rather than about its
+# contents — it is what separates a first run from a history that exists and
+# cannot be used. A file that is present but truncated, or written in a shape
+# this build does not know, arrives here as its own bytes and the renderer
+# decides; a file that was never there arrives as "".
+#
+# READ ONCE, EARLY, because `write_bridge` overwrites it on the success path and
+# the delta compares against what was there when this scan started.
+PREVIOUS_PULSE=""
+read_previous_pulse() {
+  local root file
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || return 0
+  [ -n "$root" ] || return 0
+  file="$root/.plot/state/last-pulse.json"
+  [ -f "$file" ] || return 0
+  # A HUGE OR UNREADABLE FILE COSTS THE DELTA, NEVER THE PULSE. Every failure
+  # here leaves PREVIOUS_PULSE empty, which reads as a first run — the same
+  # answer the scan gave before this existed.
+  PREVIOUS_PULSE=$(cat "$file" 2>/dev/null | tr -d '\n') || PREVIOUS_PULSE=""
+  return 0
+}
+
+write_bridge() {
+  [ "$record" = 1 ] || return 0
+  [ -n "$reading_doc" ] || return 0
+  # The bridge belongs to the REPOSITORY, not to the directory the scan was run
+  # from. Every other path here is relative to the cwd because the board spawns
+  # this from the root; the board reads the bridge at `repoRoot`, so this asks
+  # git rather than assuming the two agree.
+  local root file tmp
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || return 0
+  [ -n "$root" ] || return 0
+  file="$root/.plot/state/last-pulse.json"
+  mkdir -p "$root/.plot/state" 2>/dev/null || return 0
+  tmp="$file.$$.tmp"
+  # `at` is when the scan COMPLETED, which is what `pulse-bridge.ts:81` asks for
+  # — "NOT when it was written" — and the two are the same instant here.
+  printf '{"version":1,"at":%s,"pulse":%s,"ages":[],"branchUrlBase":"","approvedAt":[],"ideaPlans":[]}' \
+    "$(( $(date +%s) * 1000 ))" "$reading_doc" > "$tmp" 2>/dev/null || {
+      rm -f "$tmp" 2>/dev/null
+      return 0
+    }
+  mv -f "$tmp" "$file" 2>/dev/null || rm -f "$tmp" 2>/dev/null
+  return 0
+}
+
+# THE READING, COMPOSED ONCE. Two consumers read it — `--json`/`--stream` print
+# it, and `write_bridge` records it — and composing it twice is how the printed
+# document and the recorded one start to disagree. Assembled only when
+# `build_doc` is on, because the branch objects inside `$json_plans` cost
+# `merge-tree` per unlanded branch.
+if [ "$build_doc" = 1 ]; then
+  # BEFORE THE DOCUMENT IS COMPOSED AND LONG BEFORE IT IS WRITTEN. The delta
+  # compares against the pulse that was on disk when this scan started, and
+  # `write_bridge` replaces that file on the success path below.
+  read_previous_pulse
   # `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".
   #
   # `head` repeats `local_head` as an alias for one release. The board reads it
   # today; it goes away once the board reads the pair.
-  printf '{"main":"%s","read_ref":"%s","local_head":"%s","head":"%s",' \
+  reading_doc=$(printf '{"main":"%s","read_ref":"%s","local_head":"%s","head":"%s",' \
     "$(json_str "$MAIN")" "$(json_str "$READ_REF")" "$(json_str "$LOCAL_HEAD")" \
-    "$(json_str "$HEAD_SHORT")"
+    "$(json_str "$HEAD_SHORT")")
   # Three more facts about the EVIDENCE, not about the fleet — a consumer that
   # renders the numbers below should be able to say how much to trust them.
   # They answer the question `read_ref` raises: that field names the ref, and
@@ -3439,13 +4188,42 @@ if [ "$as_json" = 1 ]; then
   # `fetch_failed` used to be discarded by `2>/dev/null`, so refs an hour old
   # were reported with the confidence of refs a second old. `plan_source` says
   # whether the plan list came from the ref or fell back to this checkout.
-  printf '"fetch_failed":%s,"fetch_error":"%s","plan_source":"%s","plans":[%s],' \
+  reading_doc+=$(printf '"fetch_failed":%s,"fetch_error":"%s","plan_source":"%s","plans":[%s],' \
     "$([ "$FETCH_FAILED" = 1 ] && echo true || echo false)" \
-    "$(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"
+    "$(json_str "$FETCH_ERROR")" "$(json_str "$PLAN_SOURCE")" "$json_plans")
+  reading_doc+=$(printf '"summary":{"plans":%d,"waves":%d,"branches":%d,"claimed":%d,' \
+    "$n_plans" "$n_waves" "$n_branches" "$n_claimed")
+  # `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.
+  reading_doc+=$(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")
+fi
+
+# --json: the same derivation as the prose above, rendered for machines. It is
+# an OUTPUT MODE and nothing more — it composes with --offline/--no-fetch/
+# --loose rather than implying any of them, so the board's data depends on what
+# it asked for, not on how it asked. --next wins over it (handled above): that
+# is a different question with a one-line answer.
+if [ "$as_json" = 1 ]; then
+  # THE SCAN COMPLETED, so the bridge may be replaced. Before the document is
+  # printed rather than after: a consumer that reads the terminal line and then
+  # kills us must still find the file written.
+  write_bridge
+  # --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 `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":"reading","reading":'
+  printf '%s' "$reading_doc"
   [ "$stream" = 1 ] && printf '}'
   printf '\n'
   exit 0
@@ -3459,6 +4237,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.
@@ -3492,5 +4299,33 @@ if [ "$PLAN_SOURCE" != "ref" ]; then
   echo "  note: origin/$MAIN could not be read — plans were listed from this"
   echo "        checkout instead, so the list is only as current as your last pull."
 fi
+# THE PROSE PATH'S TERMINAL POINT, and the counterpart to the `--json` write
+# above. `/plot-pulse` runs this path — it passes `--log-pulse` and no `--json`
+# — so without a write here the boardless repository the plan names would still
+# accumulate no history. A no-op unless `--log-pulse` turned assembly on.
+#
+# Below every `note:` the report emits and above the sentence that says the scan
+# finished: a scan killed while printing its notes has not completed, and must
+# not replace the last good answer.
+# WHAT CHANGED SINCE THE LAST PULSE, above the line that says this one
+# finished. The rule is `pulseDelta` in the domain and this prints what it
+# decided — no comparison happens here, and one written here would be the
+# second implementation of a rule that already has tests.
+#
+# ONLY WHERE A PULSE WAS PRODUCED FOR SOMEBODY TO READ. `build_doc` is what says
+# the reading was assembled at all, and `record` is what says this run is one of
+# the two that produce a pulse rather than answer a query. A `--next` caller
+# asking what to work on is told nothing new.
+#
+# EVERY FAILURE IS SILENT AND COSTS ONLY THE DELTA. A missing artifact, an
+# unreadable previous pulse, a node that will not start — the full report below
+# is exactly what it was before this existed, which is the degradation this
+# whole line is optional against.
+if [ "$build_doc" = 1 ] && [ "$record" = 1 ] && [ -n "$reading_doc" ]; then
+  delta_out=$(printf '%s\n%s\n' "$PREVIOUS_PULSE" "$reading_doc" \
+    | node "$script_dir/board/plot-delta.mjs" 2>/dev/null) || delta_out=""
+  [ -n "$delta_out" ] && { printf '%s\n' "$delta_out"; echo; }
+fi
+write_bridge
 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"