@plot-pm/board 0.14.4 → 0.16.0

package/plot-fleet-scan.sh

@@ -16,6 +16,14 @@
 #   --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.
+#               WHEN THERE ARE NONE IT SAYS WHY, ON STDERR: whether every
+#               candidate in an eligible wave is taken, or no eligible wave held
+#               a startable branch at all. Two silences a reader cannot
+#               otherwise tell apart (#994). Stdout stays a bare branch list
+#               because `plot-dispatch.sh` pipes it through `sort -u` and
+#               dispatches every line, and the exit code stays 1 either way, so
+#               no caller's gate moves. An estate with NO plans exits earlier
+#               and says nothing — there is no candidate set to describe.
 #   --loose     a prior wave counts as satisfied when its branches carry PUSHED
 #               work, not only merged work. Buys throughput, pays in rebase
 #               risk — the plan requires a stated reason for using it. Default
@@ -88,12 +96,21 @@
 # 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 waiting=1 prereq_missing=0 merge_detect=pr-merge host=ok main=main
+#             summary: plans=1 waves=3 branches=5 claimed=1 claimable=2 eligible=2 blocked=1 deferred=1 waiting=1 prereq_missing=0 merge_detect=pr-merge host=ok main=main
 #         `host` is one of ok, partial, throttled, secondary, failed, unasked —
 #         `partial` means some of the host's states answered and some did not,
 #         so the PR readings below are incomplete rather than absent.
 #         `blocked` counts WAVES an earlier wave holds; `waiting` and
 #         `prereq_missing` count BRANCHES their `waits:` annotation holds.
+#         `claimable` counts BRANCHES a worker may take now, and it is the key
+#         the offer paths agree with — `--next` names one of them and
+#         `--list-eligible` names all of them. `eligible=` carries the SAME
+#         number beside it and is kept for consumers that read it; it was the
+#         only name this count had until 2026-09-25, sitting between two wave
+#         counts while counting branches, so a wave printed `eligible` in the
+#         body while the footer read `eligible=0` and both were right about
+#         different questions (#994). A reader wanting the WAVE answer counts
+#         the body's verdicts; no footer key reports it.
 #         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
@@ -116,13 +133,21 @@
 #         lifecycle state, verbatim from plot-plan-meta.sh, and the half of a
 #         row's phase git cannot answer. Which column a row reads is composed
 #         from it AND the branch state one layer up; this script decides nothing.
-#         The plan set also includes plans delivered inside a rolling 24 h
-#         window (see "the last day of finished work"), so work does not
-#         disappear at the moment it becomes finished.
-#         Plans are enumerated from `origin/<main>` (`git ls-tree`/`git show`),
-#         NOT from the working tree — so the list describes one atomic commit
-#         and does not change while rebases and worker commits rewrite the
-#         checkout underneath a running fleet. A consequence worth stating: an
+#         The plan set also includes every plan at `Delivered`, until it is
+#         `Released` (see "the release scope"), so DONE names what the next
+#         release ships.
+#         Plans are enumerated from REFS (`git ls-tree`/`git show`), NOT from
+#         the working tree — so the list describes committed state and does not
+#         change while rebases and worker commits rewrite the checkout
+#         underneath a running fleet. `origin/<main>` first, then each prefixed
+#         branch's own tree for the plans the default branch does not carry:
+#         a plan created with `Impl: same branch` lives only on its work branch
+#         until that branch merges, and reading main alone reported its branch as
+#         an anonymous row with `plan: ""` while the Board tab showed the same
+#         plan as a Draft card (#972). A plan path is taken ONCE — the default
+#         branch wins, and among branches the first to carry it — because two
+#         branches cut from one point hold the same file and a row per branch
+#         would report one plan as several. A consequence worth stating: an
 #         UNCOMMITTED plan is invisible, deliberately — the fleet view shows
 #         what is shared, and a plan only this machine has cannot be claimed by
 #         any worker. --json carries `plan_source` (ref | worktree), which
@@ -228,6 +253,8 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # plot-dispatch.sh so a worker has ONE state, not one per reader.
 # shellcheck source=plot-worker-state.sh
 . "$script_dir/plot-worker-state.sh"
+# Every temp path this scan creates, and its only EXIT/INT/TERM traps.
+. "$script_dir/plot-tmp.sh"
 cfg() { "$script_dir/plot-config.sh" get "$1" "${2:-}"; }
 
 do_fetch=1
@@ -548,14 +575,15 @@ fi
 # outlives the scan that fetched it — a stale `merged` read from a previous run
 # is exactly the fabricated verdict the failure direction above forbids.
 #
-# Cleanup is trapped rather than trailing: the script exits early in several
+# Cleanup is registered rather than trailing: the script exits early in several
 # places (--next with nothing to start, no active plans), and a temp directory
-# left behind on those paths would accumulate one per poll.
+# left behind on those paths would accumulate one per poll. It goes through
+# `plot-tmp.sh`'s one registry: this cache had its own EXIT trap, and the
+# `REF_TMP` trap below replaced it, so every scan left one `tmp.*` directory of
+# ~955 files behind (measured 2026-09-30).
 HOST_STATE_CACHE=""
 if [ "$HOST_LOOKUP_OK" = 1 ]; then
-  HOST_STATE_CACHE=$(mktemp -d 2>/dev/null) || HOST_STATE_CACHE=""
-  [ -n "$HOST_STATE_CACHE" ] \
-    && trap 'rm -rf "$HOST_STATE_CACHE" 2>/dev/null || true' EXIT INT TERM
+  plot_tmpdir HOST_STATE_CACHE fleet-host-state 2>/dev/null || HOST_STATE_CACHE=""
 fi
 
 # The cache key. Shared by the join and by `host_pr_state`, because the two
@@ -697,49 +725,11 @@ REMOTE_REFS=$(git for-each-ref --format='%(refname:strip=3)%09%(objectname)' \
 # falls back to the listing there, which is what it has always done.
 TRACKED_BRANCHES=$(printf '%s\n' "$REMOTE_REFS" | cut -f1 | grep -v '^HEAD$' | grep -v '^$' | tr '\n' ' ')
 
-prefill_pr_states() {
-  [ "$HOST_LOOKUP_OK" = 1 ] || return 0
-  [ -n "$HOST_STATE_CACHE" ] || return 0
-  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".
-  #
-  # `--rich` adds `checks` and `draft` to the response — the fields `--loose`
-  # needs to verify that a prior wave's PR is actually green and ready.
-  # Requested unconditionally because the cost is zero on GitHub (same GraphQL
-  # call) and bounded on Bitbucket (N extra calls only when CI: jenkins is
-  # 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.
-  #
-  # 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}"
-  # THE BRANCHES THIS SCAN TRACKS, HANDED TO THE HOST (#333). The adapter uses
-  # them only where it can — the Bitbucket arm sweeps its REST endpoint once per
-  # branch per state — and ignores them everywhere else, so the GitHub arm makes
-  # the single call it always made. Passing them unconditionally keeps one call
-  # shape here rather than a backend test this script has no business making.
-  #
-  # AN EMPTY SET PASSES NOTHING and the adapter lists as before. See
-  # `TRACKED_BRANCHES`: a completeness claim over an empty set would license
-  # `NONE` for branches nobody asked about.
-  _branch_args=()
-  for _tb in $TRACKED_BRANCHES; do _branch_args+=(--branch "$_tb"); done
-  host_err=$("$script_dir/plot-host.sh" pr-list --state all --limit "$PR_LIST_LIMIT" --rich \
-         ${_branch_args[@]+"${_branch_args[@]}"} \
-         </dev/null 2>&1 >"$host_list_out"); rc=$?
-  js=$(cat "$host_list_out" 2>/dev/null)
+# ONE `pr-list` CALL'S EXIT, READ AS A VERDICT WORD in `_plv` — a global
+# rather than stdout, so the two calls in `prefill_pr_states` fork nothing to
+# classify themselves. `$1` is the exit code, `$2` the call's stderr.
+pr_list_verdict() {
+  local rc="$1" err="$2"
   # A PARTIAL ANSWER TAKES THE PARSE PATH AND STILL DEGRADES THE VERDICT, which
   # is a control-flow change rather than another `case` arm below: every other
   # non-zero rc sets a verdict and returns BEFORE `$js` is read, because there
@@ -750,9 +740,11 @@ prefill_pr_states() {
   # BOTH HALVES ARE REQUIRED. Falling through without setting the verdict would
   # report `ok` over a page missing a whole state, which is #912; returning
   # early would throw away rows the host did answer with.
-  if [ "$rc" -eq 7 ]; then
-    HOST_VERDICT=partial
-  elif [ "$rc" -ne 0 ]; then
+  if [ "$rc" -eq 0 ]; then
+    _plv=ok
+  elif [ "$rc" -eq 7 ]; then
+    _plv=partial
+  else
     # 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
@@ -774,10 +766,10 @@ prefill_pr_states() {
     # 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
+      5) _plv=throttled ;;
+      6) _plv=secondary ;;
+      4) _plv=unasked ;;
+      *) case "$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:
@@ -794,7 +786,7 @@ prefill_pr_states() {
            # 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 ;;
+             _plv=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
@@ -813,19 +805,123 @@ prefill_pr_states() {
            # 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 ;;
+             _plv=unasked ;;
+           *) _plv=failed ;;
          esac ;;
     esac
-    return 0
   fi
-  # The list arrived. An empty one arrived too — that is the whole distinction.
+}
+
+# WHICH OF TWO VERDICTS IS WORSE. Every word that returns before a payload is
+# read outranks both words that parse one, so a failed call can never be
+# reported as `ok` or `partial` beside a call that answered.
+# The rank is set in `_plr`, for the same no-fork reason as `_plv`.
+pr_list_verdict_rank() {
+  case "$1" in
+    ok) _plr=0 ;; partial) _plr=1 ;; unasked) _plr=2 ;;
+    secondary) _plr=3 ;; throttled) _plr=4 ;; *) _plr=5 ;;
+  esac
+}
+
+prefill_pr_states() {
+  [ "$HOST_LOOKUP_OK" = 1 ] || return 0
+  [ -n "$HOST_STATE_CACHE" ] || return 0
+  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".
+  #
+  # `--rich` adds `checks` and `draft` to the response — the fields `--loose`
+  # needs to verify that a prior wave's PR is actually green and ready. The
+  # BEHAVIOUR change is in `pr_ready`, which reads the check rollup from the
+  # cache rather than making a per-branch host call.
+  #
+  # THE ROLLUP IS ASKED OF OPEN PRS ONLY. On GitHub it is `statusCheckRollup`,
+  # and its cost scales with the rows it is asked for. Measured 2026-09-25 on
+  # this repo through `plot-host.sh`: 957 PRs (920 merged, 34 closed, 3 open),
+  # and the one `--state all --rich` call took ~37 s of a ~55 s scan. A merged
+  # or closed PR's checks cannot change, and `pr_ready` reads them only for an
+  # open one. So TWO calls: `--state open --rich` for the PRs whose checks can
+  # still move, and `--state all` without `--rich` for every PR's state.
   #
-  # A PARTIAL VERDICT IS NOT OVERWRITTEN HERE. Exit 7 reaches this line
-  # deliberately, because its rows must be parsed; an unguarded `ok` would
-  # undo the one thing that distinguishes an incomplete page from a whole one
-  # and report #912 as a healthy reading.
-  [ "$HOST_VERDICT" = partial ] || HOST_VERDICT=ok
+  # 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.
+  local open_list_out host_list_out open_err rc_open
+  open_list_out="${HOST_STATE_CACHE:+$HOST_STATE_CACHE/pr-list-open.json}"
+  open_list_out="${open_list_out:-/dev/null}"
+  host_list_out="${HOST_STATE_CACHE:+$HOST_STATE_CACHE/pr-list.json}"
+  host_list_out="${host_list_out:-/dev/null}"
+  # THE BRANCHES THIS SCAN TRACKS, HANDED TO THE HOST (#333). The adapter uses
+  # them only where it can — the Bitbucket arm sweeps its REST endpoint once per
+  # branch per state — and ignores them everywhere else, so the GitHub arm makes
+  # the single call it always made. Passing them unconditionally keeps one call
+  # shape here rather than a backend test this script has no business making.
+  #
+  # AN EMPTY SET PASSES NOTHING and the adapter lists as before. See
+  # `TRACKED_BRANCHES`: a completeness claim over an empty set would license
+  # `NONE` for branches nobody asked about.
+  _branch_args=()
+  for _tb in $TRACKED_BRANCHES; do _branch_args+=(--branch "$_tb"); done
+  # BOTH CALLS TAKE `--limit` AND THE BRANCHES. Without `--limit` the host
+  # returns 30 (see `PR_LIST_LIMIT`). The branches make the Bitbucket arm sweep
+  # the open state exactly rather than list a fixed 50 of it: an open PR
+  # missing from the rich payload has NO row at all once the plain payload's
+  # OPEN rows are dropped below, and a missing row reads as "no PR".
+  #
+  # OPEN FIRST, THEN ALL. A PR that merges between the two calls then carries
+  # a rich OPEN row and a plain MERGED one, and the rank keeps OPEN — stale by
+  # seconds, and the next scan corrects it.
+  open_err=$("$script_dir/plot-host.sh" pr-list --state open --limit "$PR_LIST_LIMIT" --rich \
+         ${_branch_args[@]+"${_branch_args[@]}"} \
+         </dev/null 2>&1 >"$open_list_out"); rc_open=$?
+  # THE VERDICT IS THE WORSE OF THE TWO, never the last one. A rich call
+  # throttled while the plain one answers leaves `checks` absent for every open
+  # PR, so `--loose` degrades to strict — and a footer reading `host=ok` would
+  # give no reason for it.
+  #
+  # A FAILED CALL PREFILLS NOTHING, whichever of the two failed. That is the
+  # single call's behaviour carried over: a verdict other than `ok` or
+  # `partial` sets the verdict and returns before any payload is read. A
+  # failed `open` call therefore decides the outcome alone, and the `all` call
+  # is not made: its answer could not change the verdict's direction, and on a
+  # throttled host it would spend quota on a payload nothing reads.
+  pr_list_verdict "$rc_open" "$open_err"; _v_open=$_plv
+  case "$_v_open" in ok|partial) ;; *) HOST_VERDICT=$_v_open; return 0 ;; esac
+  host_err=$("$script_dir/plot-host.sh" pr-list --state all --limit "$PR_LIST_LIMIT" \
+         ${_branch_args[@]+"${_branch_args[@]}"} \
+         </dev/null 2>&1 >"$host_list_out"); rc=$?
+  pr_list_verdict "$rc" "$host_err"; _v_all=$_plv
+  pr_list_verdict_rank "$_v_open"; _r_open=$_plr
+  pr_list_verdict_rank "$_v_all"
+  if [ "$_r_open" -gt "$_plr" ]; then HOST_VERDICT=$_v_open; else HOST_VERDICT=$_v_all; fi
+  case "$HOST_VERDICT" in ok|partial) ;; *) return 0 ;; esac
+  # THE MERGE, AND THE TRAP IT AVOIDS. An open PR is in BOTH payloads — rich
+  # from the `open` call, plain from the `all` call — and both rows rank 1 in
+  # the dedup below. With the sort key exhausted, `sort` compares whole lines,
+  # and the plain row's `-` sentinel (0x2D) sorts before any letter: the plain
+  # row wins every time and the rollup is lost for 100% of open PRs.
+  #
+  # So the `all` payload's OPEN rows are dropped before the concatenation, and
+  # each branch contributes one OPEN row at most. Those rows are unused: the
+  # `open` call already answered for every open PR, with its rollup.
+  #
+  # THE COMPLETENESS COUNT IS TAKEN FROM THE `all` PAYLOAD BEFORE THE FILTER.
+  # `.list-complete` compares a row count against `PR_LIST_LIMIT`, and a count
+  # taken after the filter can fall below the limit for a list that reached it
+  # — a truncated list then reads as whole, and a cache miss derives `NONE` for
+  # a branch that has a PR. The `open` payload is counted too, since it is a
+  # page of its own.
+  _pr_rows=$(grep -c '"state":"[A-Z]*","head":"' "$host_list_out" 2>/dev/null) || _pr_rows=0
+  _pr_open_rows=$(grep -c '"state":"[A-Z]*","head":"' "$open_list_out" 2>/dev/null) || _pr_open_rows=0
+  js=$(cat "$open_list_out" 2>/dev/null; grep -v '"state":"OPEN","head":"' "$host_list_out" 2>/dev/null)
   # `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 —
@@ -860,12 +956,8 @@ prefill_pr_states() {
   # response, which is now only an error case) reads as empty and `pr_ready`
   # treats it as `unknown`, which degrades to strict — the safer direction.
   local last="" chk dft
-  # Rows parsed, for the completeness test below. Counted here because this is
-  # the one place every row passes through.
-  _pr_rows=0
   while IFS="	" read -r st chk dft br; do
     [ -n "$br" ] && [ -n "$st" ] || continue
-    _pr_rows=$((_pr_rows + 1))
     [ "$br" = "$last" ] && continue
     last="$br"
     # A PLAIN row (no `--rich` fields) carries `-` in the checks/draft slots so
@@ -930,10 +1022,12 @@ EOF
   # records on Bitbucket, where `bb pr list` is silently partial past 50 PRs per
   # state.
   #
-  # Counted from the rows actually parsed rather than from the raw payload, so a
-  # malformed line that the `sed` skipped cannot inflate the count into a false
+  # Counted from the rows carrying the fields the `sed` anchors on, so a
+  # malformed line that the parse skips cannot inflate the count into a false
   # claim of completeness. Fewer rows than the limit means the host had no more
-  # to give; equal to it means it may have.
+  # to give; equal to it means it may have. BOTH PAGES must be short: the
+  # `open` page is a listing of its own, and a truncated one drops open PRs
+  # the filtered `all` page no longer carries.
   #
   # AN EMPTY LIST IS NOT A COMPLETE ONE, and the test that caught this is the
   # reason it is written down. A host that exits 0 while printing nothing —
@@ -971,11 +1065,21 @@ EOF
   # unjoined branch and still answers correctly — the per-branch N+1 that #216
   # removed. That is why withholding the marker is always the safe direction and
   # is what every failure path here does.
+  #
+  # THE `open` CALL MUST BE WHOLE FOR EITHER CLAIM. The `all` call's OPEN rows
+  # were dropped above, so an `open` answer that is short — exit 7, or a sweep
+  # that did not state its completeness — leaves open PRs with no row at all,
+  # and completeness would turn those misses into `NONE`.
+  [ "$_v_open" = ok ] || return 0
   case "$host_err" in
     *"pr-list sweep complete"*)
-      printf '1' > "$HOST_STATE_CACHE/.list-complete" 2>/dev/null || true ;;
+      case "$open_err" in
+        *"pr-list sweep complete"*)
+          printf '1' > "$HOST_STATE_CACHE/.list-complete" 2>/dev/null || true ;;
+      esac ;;
     *)
-      if [ "$_pr_rows" -gt 0 ] && [ "$_pr_rows" -lt "$PR_LIST_LIMIT" ] 2>/dev/null; then
+      if [ "$_pr_rows" -gt 0 ] && [ "$_pr_rows" -lt "$PR_LIST_LIMIT" ] \
+         && [ "$_pr_open_rows" -lt "$PR_LIST_LIMIT" ] 2>/dev/null; then
         printf '1' > "$HOST_STATE_CACHE/.list-complete" 2>/dev/null || true
       fi ;;
   esac
@@ -2144,37 +2248,15 @@ pr_ready() {
 }
 
 # ---------------------------------------------------------------------------
-# Recently delivered plans: the last day of finished work
+# Delivered plans: the release scope
 # ---------------------------------------------------------------------------
 #
-# The pulse read `active/` only, so a plan left the view the INSTANT it was
-# delivered — taking every branch with it. Measured on this repo: five plans
-# delivered in one day named eight branches between them, and DONE showed one,
-# because delivery and merge are minutes apart and only whichever branch
-# happened to sit in the gap survived. A group that is full by accident is
-# worse than one that is empty by rule.
-#
-# A ROLLING 24 HOURS, not the calendar day. Literally "delivered today" is
-# easier to explain and wrong at exactly the wrong moment: a plan delivered at
-# 23:50 vanishes ten minutes later, mid-session, while the branches it names
-# are still on screen. 24 is also the one freshness bound this repo already
-# uses (`Claim stale after`), so it is one unit to learn rather than two.
-#
-# THE WINDOW FILTERS BEFORE THE PARSE. Measured: ~57 ms per plan through
-# plot-plan-meta.sh against a scan that already runs 500–1050 ms, so parsing
-# fourteen delivered plans to discard thirteen would roughly double the pulse —
-# and that cost grows with the archive, which only ever gets larger, while the
-# answer stays the size of a day's work. So the cheap signal comes first (the
-# delivered symlink's own mtime) and only the candidates it admits are parsed.
-#
-# The pre-filter may OVER-ADMIT AND PAY A PARSE; it may never exclude. A
-# checkout can freshen an old file, so the `Delivered:` record keeps the last
-# word — but nothing mtime rules out could have been delivered inside the
-# window. On a fresh clone or a CI worktree every file shares one checkout
-# timestamp and ALL of them are admitted: correct, merely slower, once. Reaching
-# for `git log` per plan to avoid that would spend a git call to save a parse.
-DELIVERED_WINDOW_HOURS=$(cfg "Claim stale after" "24")
-case "$DELIVERED_WINDOW_HOURS" in (*[!0-9]*|'') DELIVERED_WINDOW_HOURS=24 ;; esac
+# A plan at `Delivered` stays in the pulse until it is `Released`, whatever its
+# age. DONE holds the release scope (`done-holds-what-is-still-yours`): every
+# plan whose work has landed and whose version has not shipped. A 24-hour window
+# on the `Delivered:` record bounded this until 2026-10-01, when 25 plans awaited
+# 2.22.0 and DONE showed 10. Every plan file is parsed in one pass anyway, so the
+# window bought no parse time; it only hid work the next release ships.
 
 
 # ---------------------------------------------------------------------------
@@ -2340,52 +2422,7 @@ changed_ago_of() { # $1=branch → "<seconds since>\t<epoch of>" for the newest
   if [ "$newest" -gt "$now" ]; then printf '0\t%s' "$newest"; else printf '%s\t%s' "$((now - newest))" "$newest"; fi
 }
 
-# A plan whose delivered symlink was touched inside the window. `find -newermt`
-# is not portable to every BSD find in the wild, so the cutoff is computed and
-# compared with `stat` — one stat per file, no parse.
-delivered_candidates() {
-  local cutoff now link mtime
-  now=$(date +%s)
-  cutoff=$((now - DELIVERED_WINDOW_HOURS * 3600))
-  for link in "$DELIVERED_DIR"*.md; do
-    [ -e "$link" ] || continue
-    # `stat` follows the symlink, which is what we want: the TARGET is the plan,
-    # and a plan edited after delivery must still admit. An unreadable time
-    # ADMITS rather than excludes — the pre-filter may only over-admit, and the
-    # `Delivered:` record has the last word either way.
-    mtime=$(file_mtime "$link") || { printf '%s\n' "$link"; continue; }
-    [ "$mtime" -ge "$cutoff" ] && printf '%s\n' "$link"
-  done
-}
 
-# Does this plan's `Delivered:` record fall inside the window? The RECORD
-# decides — mtime only chose who got asked.
-#
-# "No date, no row." A delivered plan with an empty record does not appear at
-# all: no date means no membership in any window, the same rule the waiting age
-# already follows. Showing it always would create the one row that can never
-# age out of DONE, and the missing record is a bookkeeping fault
-# plot-reconcile-scan.sh exists to report — a view that quietly compensates
-# for it makes the fault harder to see.
-#
-# A BARE DATE IS ANCHORED AT THE END OF ITS DAY, not at midnight, and this is
-# the one detail that makes "rolling, not the calendar day" true rather than
-# merely stated. Every `Delivered:` record in this repo is a bare date, which
-# names no time — so anchoring at 00:00 measures from up to a day BEFORE the
-# delivery, and the window collapses back into exactly the calendar boundary
-# the rolling window exists to avoid: a plan delivered at 23:50 would be an
-# hour from expiry the moment it was written, and gone ten minutes later
-# mid-session while the branches it names are still on screen.
-#
-# Anchoring at 23:59:59 over-admits by at most the length of the delivery day.
-# That is the same direction the mtime pre-filter is allowed to err in, and for
-# the same reason: showing a finished plan slightly too long costs a row, while
-# dropping one mid-session costs the reader the work they were looking at. A
-# record that DOES carry a time is honoured exactly, so the imprecision belongs
-# to the record rather than to the rule.
-# The rule itself now runs inside the ONE estate parse below (`in_window`),
-# because asking it per plan meant an interpreter per plan. What it decides is
-# unchanged; only the number of processes that decide it is.
 
 # ---------------------------------------------------------------------------
 # Plan enumeration: from the REF, not from the tree
@@ -2476,15 +2513,15 @@ ref_ls() { # $1=dir → newline-separated paths under it in origin/$MAIN
 # `ref_plan_file` is called as `$(ref_plan_file ...)`, which runs it in a
 # SUBSHELL. A lazy `[ -z "$REF_TMP" ] && REF_TMP=$(mktemp -d)` inside it
 # assigns in the child and the parent never sees it — so every call made a
-# fresh directory, the parent's variable stayed empty, and the EXIT trap
-# cleaned nothing. Measured while writing this: three plans, three temp dirs,
+# fresh directory, the parent's variable stayed empty, and the exit cleanup
+# removed nothing. Measured while writing this: three plans, three temp dirs,
 # none removed. The lifetime is owned out here, where the trap can see it.
 REF_TMP=""
 if [ "$PLAN_SOURCE" = "ref" ]; then
-  REF_TMP=$(mktemp -d "${TMPDIR:-/tmp}/plot-fleet-ref.XXXXXX") || REF_TMP=""
   # The scan is read-only and short-lived, and the board polls it every 5 s —
-  # a directory that outlives the run would accumulate one per poll.
-  [ -n "$REF_TMP" ] && trap 'rm -rf "$REF_TMP"' EXIT INT TERM
+  # a directory that outlives the run would accumulate one per poll, so the
+  # helper removes it at exit.
+  plot_tmpdir REF_TMP fleet-ref || REF_TMP=""
   # No temp dir means no way to hand the parser a file, so the ref path cannot
   # work. Falling back to the checkout is the honest answer, and it announces
   # itself through `plan_source` exactly like an unreadable ref.
@@ -2625,6 +2662,68 @@ ref_plan_file() { # $1=path in ref → temp file path, or "" when unreadable
   printf '%s' "$out"
 }
 
+# ---------------------------------------------------------------------------
+# A branch's own plans
+# ---------------------------------------------------------------------------
+#
+# A plan created with `Impl: same branch` lives ONLY on its work branch until
+# that branch merges. The enumeration above reads `origin/$MAIN` and finds
+# nothing, so the branch carrying the plan reached the pulse as an anonymous row
+# with `plan: ""` while `/api/board` showed the same plan as a Draft card.
+# Measured on Plot 2.20.0 (#972): two tabs of one board disagreeing about
+# whether a plan exists, which is worse than either answer alone.
+#
+# `board.ts:802-831` already solved this and the RULE is what transfers, not the
+# call: the scan keeps its own reading (Manifesto Principle 3) and the two stay
+# separate implementations. `readBranchPlans` is the reference.
+#
+# A NARROW READER RATHER THAN A REF ARGUMENT ON THE FOUR HELPERS ABOVE, and the
+# reason is `$REF_TMP`'s namespace. `ref_plan_file` caches by `basename "$p"` in
+# one flat directory, deliberately, so the filename a report prints is the
+# plan's own. Widening that across refs would let `origin/A:docs/plans/x.md` and
+# `origin/B:docs/plans/x.md` overwrite each other SILENTLY — the dedup's concern
+# ("one plan reported as several") inverted into two plans reported as one,
+# carrying whichever content was written last. A per-branch subdirectory makes
+# the collision unrepresentable instead of unlikely. The batch materialiser at
+# `:2543` is also built around one ref by construction: it keys a single
+# `cat-file --batch` stream by basename off one `PLAN_MODES`.
+#
+# REGULAR BLOBS ONLY, never mode 120000. A symlink blob holds its TARGET PATH as
+# content, so parsing one hands plot-plan-meta.sh a line of text where a plan
+# should be, and `$ACTIVE_DIR`'s links would double-count every indexed plan.
+# `$PLAN_DIR` alone is listed, with modes — which is also why the ref-space
+# symlink walk in `ref_plan_file` is deliberately NOT ported here: filtering the
+# links out first means there is no link left to follow.
+branch_plan_paths() { # $1=branch → regular .md blob paths under $PLAN_DIR
+  # An UNREADABLE REF CONTRIBUTES NOTHING, silently — an empty set, exactly as
+  # `planPathsInTree` returns. It never produces a blank or guessed plan, and
+  # this is asked once per branch where a fetch may legitimately have missed one.
+  git ls-tree -z "origin/$1" -- "$PLAN_DIR" </dev/null 2>/dev/null \
+    | tr '\0' '\n' \
+    | awk -F'\t' '$1 ~ /^100644 |^100755 / && $2 ~ /\.md$/ { print $2 }' || true
+}
+
+# One branch plan blob, materialized where plot-plan-meta.sh can parse it.
+#
+# NAMED UNDER A PER-BRANCH DIRECTORY for the collision reason above. The branch
+# name is sanitized because it carries `/` by convention (`bug/…`), which would
+# otherwise name a directory that does not exist.
+branch_plan_file() { # $1=branch, $2=path in that branch → temp file, or ""
+  local branch="$1" p="$2" content dir out
+  [ -n "$REF_TMP" ] || return 1
+  content=$(git show "origin/$branch:$p" </dev/null 2>/dev/null) || return 1
+  # AN EMPTY BLOB IS SKIPPED RATHER THAN PARSED (`board.ts:817-822`): a plan
+  # file with no bytes parses to no phase, and a row with no phase belongs in no
+  # column. The emptiness test sits beside the failure test rather than
+  # replacing it, because the two are different faults.
+  [ -n "$content" ] || return 1
+  dir="$REF_TMP/branch/$(printf '%s' "$branch" | tr '/' '_')"
+  mkdir -p "$dir" 2>/dev/null || return 1
+  out="$dir/$(basename "$p")"
+  printf '%s\n' "$content" > "$out" 2>/dev/null || return 1
+  printf '%s' "$out"
+}
+
 # Resolve which plans to report on.
 #
 # TWO PARALLEL ARRAYS, because a plan now has two paths that must not be
@@ -2727,7 +2826,7 @@ is_plan_phase() { # $1=normalized phase → 0 when this file is a plan
 #
 # `record` types, one per line, all tab-separated and all prefixed by the plan
 # file they describe:
-#   P <file> <phase> <delivered_in_window>   one per parsed file
+#   P <file> <phase>   one per parsed file
 #   W <file> <wave-idx> <branch> <deferred> <why> <wave-name> <claim>
 #
 # NO ASSOCIATIVE ARRAYS. `/bin/bash` on macOS is 3.2 and this script uses no
@@ -2745,7 +2844,6 @@ is_plan_phase() { # $1=normalized phase → 0 when this file is a plan
 # gave when it failed.
 plan_meta_files=()
 plan_meta_phases=()
-plan_meta_inwindow=()
 plan_meta_waves=()
 
 # Parses every plan file given, filling the four arrays above. Called ONCE.
@@ -2756,33 +2854,6 @@ parse_plan_estate() { # $@=files to parse
     | python3 -c '
 import json, re, sys, time
 
-window = float(sys.argv[1]) * 3600
-now = time.time()
-
-def in_window(raw):
-    """The `Delivered:` record against the rolling window — the same rule the
-    per-plan test applied, moved into the one pass. A record whose date does
-    not parse is dropped rather than coerced: Date-style leniency would turn a
-    typo into a confident answer. A record with no time anchors at 23:59:59,
-    so a plan delivered at 23:50 is not an hour from expiry the moment it is
-    written. A FUTURE record is INSIDE (negative age), because hiding a live
-    plan for a mistyped year costs more than showing one."""
-    raw = (raw or "").strip()
-    if not raw:
-        return False
-    m = re.match(r"(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}))?", raw)
-    if not m:
-        return False
-    y, mo, dy, hh, mi = m.groups()
-    timed = hh is not None
-    try:
-        at = time.mktime((int(y), int(mo), int(dy),
-                          int(hh) if timed else 23, int(mi) if timed else 59,
-                          0 if timed else 59, 0, 0, -1))
-    except (ValueError, OverflowError):
-        return False
-    return (now - at) <= window
-
 def clean(s):
     return str(s).replace("\t", " ").replace("\n", " ")
 
@@ -2800,8 +2871,7 @@ for line in sys.stdin:
     f = d.get("file")
     if not f:
         continue
-    print("\t".join(["P", clean(f), clean(d.get("phase", "")),
-                     "1" if in_window(d.get("delivered_raw")) else "0"]))
+    print("\t".join(["P", clean(f), clean(d.get("phase", ""))]))
     for i, w in enumerate(d.get("waves", []) or []):
         name = w.get("name")
         for b in w.get("branches", []) or []:
@@ -2828,7 +2898,7 @@ for line in sys.stdin:
                 (b.get("deferred_reason") or "-"),
                 (b.get("waits_on") or "-"),
                 name or "-", b.get("claimed") or "-"]))
-' "$DELIVERED_WINDOW_HOURS" 2>/dev/null) || records=""
+' 2>/dev/null) || records=""
 
   local kind file rest
   while IFS=$'\t' read -r kind file rest; do
@@ -2836,9 +2906,8 @@ for line in sys.stdin:
     case "$kind" in
       P)
         plan_meta_files+=("$file")
-        # `rest` is "<phase>\t<inwindow>"; both are single tokens with no tabs.
-        plan_meta_phases+=("${rest%%	*}")
-        plan_meta_inwindow+=("${rest##*	}")
+        # `rest` is "<phase>", a single token with no tabs.
+        plan_meta_phases+=("$rest")
         plan_meta_waves+=("")
         ;;
       W)
@@ -2962,8 +3031,8 @@ else
   # was buying less than it appeared to: it keyed off the `$DELIVERED_DIR`
   # symlink's mtime, and a fresh checkout stamps every symlink at once — 56 of
   # 56 delivered links admitted here, so the parse it was meant to avoid was
-  # already being paid in full. `delivered_in_window` (the `Delivered:` record)
-  # was always the filter that actually decided, and the pre-filter's own
+  # already being paid in full. The `Delivered:` record's window was the filter
+  # that actually decided until 2026-10-01, when the phase alone took over, and the pre-filter's own
   # contract was that it may only ever OVER-admit. Removing it takes that
   # contract to its limit — strictly more correct, and on this repo not even
   # more expensive.
@@ -3013,6 +3082,56 @@ else
       cand_ids+=("$plan_path")
       cand_reads+=("$plan_blob")
     done <<< "$(ref_ls "$PLAN_DIR")"
+
+    # THEN EACH PREFIXED BRANCH'S OWN TREE, for the plans `origin/$MAIN` does
+    # not carry. Appended to the SAME candidate arrays, before the one
+    # `parse_plan_estate` call below: a second call would build a second
+    # `plan_meta_files` index and the lookup at the row loop keys on the file
+    # path, so the branch plans would parse and then be unfindable.
+    #
+    # From here the existing pipeline carries the plan unchanged — it names its
+    # branch in `## Slices`, the wave walk finds it, and the branch stops
+    # reaching the report through the plan-less loop in `fleet.ts`.
+    #
+    # THE DEDUP IS THE BOARD'S, COPIED RATHER THAN RE-DERIVED. `on_default` is
+    # every plan path the default branch carries; `seen_branch_plans` is every
+    # path already taken from an earlier branch. Two branches cut from one point
+    # carry the SAME plan file, and without the second test one plan reports as
+    # several — a regression the board measured and fixed, and the reason its
+    # comment exists.
+    #
+    # WHICH BRANCHES: `REMOTE_REFS`, already read once above, filtered by
+    # `PREFIX_RE` — the same population the board calls a prefixed branch. No
+    # second `for-each-ref`. The narrowing to PR-less branches the slice line
+    # offered was WITHDRAWN by the plan's Design section: it was a fallback
+    # against a cost that does not exist. Measured 2026-09-24, one `ls-tree`
+    # over the plan directory is ~0.00 s and the whole addition 0.24 s, 0.4% of
+    # a scan whose wall time is 95% waiting.
+    on_default=$'\n'"$(ref_ls "$PLAN_DIR")"$'\n'
+    seen_branch_plans=$'\n'
+    while IFS=$'\t' read -r branch_name _branch_sha; do
+      [ -n "$branch_name" ] || continue
+      [ "$branch_name" = "HEAD" ] && continue
+      [ "$branch_name" = "$MAIN" ] && continue
+      printf '%s' "$branch_name" | grep -Eq "^($PREFIX_RE)/" || continue
+      while IFS= read -r bp; do
+        [ -n "$bp" ] || continue
+        case "$on_default" in *$'\n'"$bp"$'\n'*) continue ;; esac
+        case "$seen_branch_plans" in *$'\n'"$bp"$'\n'*) continue ;; esac
+        plan_blob=$(branch_plan_file "$branch_name" "$bp") || continue
+        [ -n "$plan_blob" ] || continue
+        # MARKED SEEN ONLY ONCE IT IS TAKEN, matching `board.ts:823`: a blob
+        # that could not be read has not been reported, so a later branch
+        # carrying a readable copy of the same path must still get its turn.
+        seen_branch_plans="${seen_branch_plans}${bp}"$'\n'
+        # THE IDENTITY STAYS THE RELATIVE PATH. The row loop parses
+        # `plan_reads[i]` and never re-reads by the identity in `plans[i]`, so
+        # the `docs/plans/…md` path is a usable id — and the dedup above is what
+        # guarantees it cannot collide with a default-branch plan's.
+        cand_ids+=("$bp")
+        cand_reads+=("$plan_blob")
+      done <<< "$(branch_plan_paths "$branch_name")"
+    done <<< "$REMOTE_REFS"
   else
     for plan_path in "$PLAN_DIR"*.md; do
       [ -e "$plan_path" ] || continue
@@ -3066,7 +3185,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 waiting=0 prereq_missing=0 main=$MAIN"
+    echo "summary: plans=0 waves=0 branches=0 claimed=0 claimable=0 eligible=0 blocked=0 deferred=0 waiting=0 prereq_missing=0 main=$MAIN"
     exit 0
   fi
 fi
@@ -3161,7 +3280,7 @@ EOF
   echo "$total $n"
 }
 
-# WHAT WAS READ OF ONE BRANCH — ten tab-separated fields, and no decision.
+# WHAT WAS READ OF ONE BRANCH — eleven 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
@@ -3178,10 +3297,11 @@ EOF
 # 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
+# EIGHT FIELDS, NOT ELEVEN. 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 caller appends the PR list's completeness last, once per run.
 #
 # 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
@@ -3494,6 +3614,12 @@ n_plans=0 n_waves=0 n_branches=0 n_claimed=0 n_eligible=0 n_blocked=0 n_deferred
 # the footer keeps the two words apart for that reason.
 n_waiting=0 n_prereq_missing=0
 claimable=()
+# HOW MANY BRANCHES AN ELIGIBLE WAVE HOLDS THAT SOMEBODY IS ON — the fact that
+# separates "this estate has no work" from "every candidate here is taken", and
+# the only reason `--list-eligible` can say which of the two its silence means.
+# Counted across eligible waves only: a taken branch in a blocked wave was never
+# a candidate, so reporting it would name work the offer path never considered.
+n_taken_in_eligible=0
 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
@@ -3524,26 +3650,14 @@ for plan in "${plans[@]}"; do
   # is a judgment that belongs one layer up (Manifesto Principle 3).
   plan_phase="${plan_meta_phases[$meta_i]}"
 
-  # The delivered window, applied to the plans the PHASE put in the terminal
-  # group. Enumeration grouped them; the `Delivered:` RECORD decides which of
-  # them still appears.
-  #
-  # THE TEST IS THE PHASE, not the path. It read `case "$plan" in "$DELIVERED_DIR"*)`
-  # — the directory the link sat in — and that made "which group is this plan
-  # in" a fact about a symlink while "what phase is it" was a fact about the
-  # file. The old comment here noted that an active plan carrying
-  # `Phase: Delivered` was drift the window must not hide; under the phase rule
-  # that drift cannot be constructed, because there is no second place for the
-  # answer to live. One source, so nothing to disagree.
-  #
-  # Two exits, and both matter:
-  #   * the record's date has aged out of the window — ordinary expiry;
-  #   * there is NO record — "no date, no row". `reconcile-scan-accuracy.md` is
-  #     the live example; showing it would create the one row that can never
-  #     age out of DONE.
-  # Both leave before a single git call is spent on the plan's branches.
-  if is_terminal_phase "$plan_phase"; then
-    [ "${plan_meta_inwindow[$meta_i]}" = "1" ] || continue
+  # THE RELEASE SCOPE, decided by the PHASE alone. A terminal plan stays in the
+  # pulse only while it is `delivered`: its work has landed and its version has
+  # not shipped, which is what DONE holds. `released`, `rejected` and
+  # `superseded` leave, whatever their age, and leave before a single git call
+  # is spent on their branches. No date bounds it, so a plan delivered weeks
+  # before a release still names the release's contents.
+  if is_terminal_phase "$plan_phase" && [ "$plan_phase" != "delivered" ]; then
+    continue
   fi
 
   n_plans=$((n_plans + 1))
@@ -3641,12 +3755,17 @@ for plan in "${plans[@]}"; do
   # deciding it — see pass 1c.
   readings=""
   order=""
+  # THE ELEVENTH FIELD: whether the PR list held every PR (`.list-complete`,
+  # written by `prefill_pr_states`). The rule reads a `NONE` for a ref behind
+  # main as `open` only when it is true; a capped list may omit a merged PR.
+  list_complete=false
+  [ -n "$HOST_STATE_CACHE" ] && [ -f "$HOST_STATE_CACHE/.list-complete" ] && list_complete=true
   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=""
-    readings+="$(branch_readings "$br" "$deferred")	${waits:--}	?"$'\n'
+    readings+="$(branch_readings "$br" "$deferred")	${waits:--}	?	$list_complete"$'\n'
     order+="$idx	$br	$deferred	$why	${waits:--}	$wname	$claim"$'\n'
   done <<< "$wave_lines"
 
@@ -3701,7 +3820,8 @@ for plan in "${plans[@]}"; do
       # 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'
+      # Field 10 is replaced; field 11 is carried.
+      refill+="$(printf '%s' "$rd_line" | cut -f1-9)	$(waits_pr_state "$waits_br")	$(printf '%s' "$rd_line" | cut -f11)"$'\n'
     else
       refill+="$rd_line"$'\n'
     fi
@@ -3807,16 +3927,36 @@ for plan in "${plans[@]}"; do
     wname=$(printf '%s' "$states" | awk -F'\t' -v w="$wid" '$1==w {print $7; exit}')
     [ "$wname" = "-" ] && wname=""
 
-    [ "$quiet" = 1 ] || echo "  ${wname:-(unnamed)} — $verdict"
+    # THE HEADER IS HELD, NOT PRINTED — it carries a suffix that only the
+    # branch loop below can decide. `eligible` answers *are this wave's
+    # prerequisites met?* while every offer path answers *can a branch here be
+    # claimed now?*, and a wave whose branches are all taken satisfies the first
+    # and not the second. Reported 2026-09-25 (#994) from a Bitbucket estate:
+    # one wave `eligible`, eleven branches, both offer paths silent. The two
+    # computations are correct and the word was carrying both answers.
+    #
+    # The line still prints BEFORE its branches — only the decision is delayed,
+    # not the reading order — so the branch lines are buffered and flushed with
+    # it. There is exactly one `echo` in that loop, which is why buffering it
+    # costs less than threading the wave header past the six counters,
+    # `json_branches` and `outlook_branches` the loop also builds.
+    wave_header="  ${wname:-(unnamed)} — $verdict"
     # A degradation that says nothing is indistinguishable from a bug.
     # When --loose falls back to strict because the rollup cannot be had,
     # say so — an operator who passed the flag and sees strict behaviour
     # has no way to tell "the rollup said not-green" from "the rollup
     # could not be had". Both are correct refusals; only one is about
     # their PR.
+    wave_body=""
     if [ "$quiet" != 1 ] && [ "$loose" = 1 ] && [ -n "$_loose_degraded_branches" ]; then
-      echo "      (--loose degraded to strict: checks unavailable for ${_loose_degraded_branches})"
+      wave_body+="      (--loose degraded to strict: checks unavailable for ${_loose_degraded_branches})"$'\n'
     fi
+    # HOW MANY BRANCHES OF THIS WAVE ARE TAKEN, and how many claimable. Counted
+    # here rather than derived from the estate-wide `n_eligible`, which spans
+    # plans. `unknown` is in neither: the host could not be asked, so the branch
+    # is not taken and not free, and a wave holding one must never be reported
+    # as somebody else's work.
+    wave_taken=0 wave_free=0
     json_branches=""
     # 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
@@ -3867,8 +4007,17 @@ for plan in "${plans[@]}"; do
       if [ "${wave_claimable:$((branch_i - 1)):1}" = "1" ]; then
         n_eligible=$((n_eligible + 1))
         claimable+=("$br")
+        wave_free=$((wave_free + 1))
       fi
-      [ "$quiet" = 1 ] || echo "      $br — $note"
+      # TAKEN MEANS SOMEBODY HAS IT — claimed, or carrying pushed work. Read
+      # from the branch's own state rather than from the claimable flag above,
+      # because that flag is 0 for six different reasons and only these two mean
+      # a person is on it. `unknown` is excluded by naming the two states rather
+      # than by negating the flag.
+      case "$st" in
+        claimed|wip) wave_taken=$((wave_taken + 1)) ;;
+      esac
+      wave_body+="      $br — $note"$'\n'
       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.
@@ -4067,6 +4216,45 @@ for plan in "${plans[@]}"; do
       fi
     done <<< "$states"
 
+    # WHICH QUESTION THE WORD ANSWERED, said in the estate's existing
+    # vocabulary. `someone-is-on-it` is `StartabilityVerdictSchema`'s word
+    # (`packages/board/src/contract/schema.ts`) for exactly these two branch
+    # states, so the wave line and its branch lines now agree rather than
+    # offering a reader two answers to compare.
+    #
+    # A PROSE SUFFIX, NOT A SIXTH VERDICT. `$verdict` is untouched and reaches
+    # `--json`, `--stream` and the outlook byte-identical: `FleetWaveSchema`'s
+    # verdict is a strict enum, so a parsed pulse cannot carry a new word and
+    # widening it is a separate change with its own consumers.
+    #
+    # THE RULE, STATED: a wave line carries BOTH answers — the verdict, then who
+    # has it — and the suffix appears exactly when the wave is `eligible`, holds
+    # no free branch, and holds at least one branch that is `claimed` or `wip`.
+    # A wave with a free branch keeps bare `eligible`, which is what the offer
+    # paths will confirm; a wave whose only non-free branches are `unknown`
+    # keeps it too, because the host could not be asked and nobody has claimed
+    # anything.
+    #
+    # `wip` COUNTS AS TAKEN, which the plan settles three times: *"a branch
+    # counts as taken when it is claimed or in progress"*. A one-branch wave
+    # whose branch is `wip` therefore reads `eligible — someone-is-on-it`, and
+    # two tests in `fleet.test.mjs` asserted `/ — eligible$/` on exactly that
+    # shape. Their subject is the VERDICT — *"has not settled its wave"*,
+    # *"the wave must stay open"* — so the anchor moved to the verdict rather
+    # than the suffix being suppressed; the `$` was free before a suffix existed
+    # and asserted a second thing neither test meant. The other five sites
+    # carrying that anchor hold a free branch and are untouched.
+    if [ "$verdict" = "eligible" ] && [ "$wave_free" -eq 0 ] && [ "$wave_taken" -gt 0 ]; then
+      wave_header+=" — someone-is-on-it"
+    fi
+    if [ "$verdict" = "eligible" ]; then
+      n_taken_in_eligible=$((n_taken_in_eligible + wave_taken))
+    fi
+    if [ "$quiet" != 1 ]; then
+      echo "$wave_header"
+      [ -n "$wave_body" ] && printf '%s' "$wave_body"
+    fi
+
     if [ "$build_doc" = 1 ]; then
       json_waves+="${json_waves:+,}{\"name\":\"$(json_str "$wname")\""
       json_waves+=",\"verdict\":\"$verdict\",\"branches\":[$json_branches]}"
@@ -4148,6 +4336,27 @@ fi
 # "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.
 if [ "$next_only" = 1 ]; then
+  # WHY THE LIST IS EMPTY, for `--list-eligible` only, and ON STDERR. An
+  # operator reading the body's `eligible` and then getting silence here cannot
+  # tell a claimed-out estate from an empty one, and #994 is that reading: one
+  # wave eligible, eleven branches, nothing offered. The exit code still carries
+  # the answer — 1 either way — so no caller's gate moves.
+  #
+  # STDERR BECAUSE STDOUT IS A TARGET LIST. `plot-dispatch.sh:3475` pipes this
+  # stdout through `sort -u` and dispatches every line, so a sentence there
+  # becomes a branch name it tries to claim. That caller already discards
+  # stderr (`2>/dev/null`), so the sentence reaches a person and no machine.
+  #
+  # `--next` IS UNTOUCHED: its exit-1 contract is shipped, documented and
+  # tested twice, and it names ONE branch for a worker that has nothing to read
+  # a sentence with.
+  if [ ${#claimable[@]} -eq 0 ] && [ "$list_all" = 1 ]; then
+    if [ "$n_taken_in_eligible" -gt 0 ]; then
+      echo "nothing claimable: $n_taken_in_eligible branch(es) in eligible waves are taken." >&2
+    else
+      echo "nothing claimable: no eligible wave holds a startable branch." >&2
+    fi
+  fi
   [ ${#claimable[@]} -gt 0 ] || exit 1
   if [ "$list_all" = 1 ]; then
     printf '%s\n' "${claimable[@]}"
@@ -4455,4 +4664,4 @@ if [ "$build_doc" = 1 ] && [ "$record" = 1 ] && [ -n "$reading_doc" ]; then
 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 waiting=$n_waiting prereq_missing=$n_prereq_missing merge_detect=$MERGE_DETECT host=$HOST_VERDICT main=$MAIN"
+echo "summary: plans=$n_plans waves=$n_waves branches=$n_branches claimed=$n_claimed claimable=$n_eligible 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"