@plot-pm/board 0.14.4 → 0.15.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
@@ -119,10 +136,18 @@
 #         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
+#         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
@@ -697,49 +722,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 +737,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 +763,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 +783,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 +802,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 +953,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 +1019,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 +1062,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
@@ -2625,6 +2726,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
@@ -3013,6 +3176,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 +3279,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
@@ -3494,6 +3707,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
@@ -3807,16 +4026,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 +4106,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 +4315,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 +4435,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 +4763,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"