@plot-pm/board 0.14.2 → 0.14.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
   "type": "module",
   "license": "MIT",

package/plot-budget.sh

@@ -221,7 +221,7 @@ BUDGET_FALLBACK_WINDOW_MS=3600000
 # which is a reading about whichever pool was spent last — so a caller deciding
 # whether a bucket is spent must name that bucket. `graphql_budget_spent` does,
 # and this is why.
-budget_rate() {
+budget_rate_read() {
   local connector="${1:-}" account="${2:-}" bucket="${3:-}" now="${4:-}"
   local path
   [ -n "$now" ] || now="$(budget_now_ms)"
@@ -321,6 +321,171 @@ budget_rate() {
   ' "$path" 2>/dev/null || echo '{"spent":0,"spanMs":0,"perHour":null,"lines":0,"unreadable":0,"limit":null,"remaining":null,"resetAt":null,"basis":"unknown"}'
 }
 
+# THE SAME ANSWER IS SCANNED FOR ONCE PER PROCESS, and that is the whole of this
+# memo. Measured on `quatico/quaweb-website` at Plot 2.19.0: `budget.tsv` holds
+# 312589 lines across 17.6 MB, one read of it takes **516 ms** against 5 ms over
+# fifty lines, and a single `pr-list` calls this three times for the same answer.
+# The file is append-only and a process that asks twice is asking about the same
+# window, so the second scan buys nothing a caller can observe.
+#
+# THE MEMO IS A FILE, AND A VARIABLE ALONE COULD NOT HAVE WORKED. Every caller
+# in `plot-host.sh` writes `rate="$(budget_rate ...)"`, and a command
+# substitution is a SUBSHELL: a variable the function sets inside one dies when
+# the substitution closes. Measured on this branch with a counter — three
+# substituted calls on one key scanned the ledger 3 times with a variable memo
+# in place, against 1 for three direct calls. A variable memo is not slow at the
+# call sites that exist, it is ABSENT from them, and every behavioural test
+# still passes because the three answers are identical.
+#
+# `$$`, NOT `BASHPID`, IS THE SCOPE. `$$` is the invoking shell's pid and is
+# deliberately NOT updated inside a subshell, so it names the process TREE —
+# which is exactly "the life of the process" this memo is bounded by. `BASHPID`
+# tracks the fork and would give every substitution its own empty cache, which
+# is the variable memo's defect with an extra file write.
+#
+# THE COST IS PAID BACK ABOUT TWO THOUSAND TIMES. Measured here: a builtin
+# `read` of one memo line is 82 us and a write 153 us, against 188 ms for one
+# scan of a 40000-line ledger and the 516 ms reported above. The read is a
+# builtin with no fork, which is what keeps it in that range.
+#
+# PER PROCESS IS THE WHOLE BOUND. There is no TTL, no `stat` of the record and
+# no invalidation hook, because a `plot-host.sh` invocation is short-lived and a
+# memo that tried to notice the file moving would re-`stat` on every call — the
+# cost this exists to remove, re-introduced in a smaller form. `budget_append`
+# writes between two reads and the second read is deliberately served the first
+# one's answer.
+#
+# THE KEY IS THE TRIPLE, NEVER ONE FIELD OF IT. An EMPTY bucket means *every
+# bucket* and is a different question from any named one — `budget_rate_read`
+# says so in its own words above, and the two live in one process: measured with
+# a probe, one `pr-list` asks `(github,jwloka,'')` for the concurrency bound and
+# `(github,jwloka,graphql)` for the transport choice. A memo keyed on less than
+# the triple answers the first with the second's reading.
+#
+# AN EXPLICIT `now` BYPASSES THE MEMO ENTIRELY, and a reader will ask why. It is
+# a FOURTH question rather than a fourth key: a caller naming a moment is asking
+# what the record looked like THEN, and every window boundary above is computed
+# from it. Keying on it would make every lookup a miss, because the callers that
+# omit it get `budget_now_ms()` and differ by milliseconds — a memo that is dead
+# code and still passes every behavioural test. Serving a memo across different
+# `now` values would answer a named moment with another one's window. Only the
+# callers that omit it — every one in `plot-host.sh` — are memoised.
+#
+# NOT-YET-COMPUTED AND COMPUTED-TO-EMPTY ARE TWO STATES, and the FILE'S
+# EXISTENCE is what separates them. The zero object is a well-formed answer for
+# a missing record and for a `budget_path` that failed, so it is CACHED like any
+# other — a memo that treated it as no-answer-worth-keeping would restore the
+# scan on exactly the machines with nothing to scan. The entry is never empty:
+# `budget_rate_read` prints a JSON object on every path, so a zero-byte entry
+# means a torn write and is re-read rather than served.
+#
+# PUBLISHED BY `mv`, NEVER BY `>`, for `budget_slot_acquire`'s reason one
+# paragraph down: a redirect creates the NAME before the CONTENT, so a sibling
+# subshell can open the file and read half an answer. The rename is atomic
+# within a directory, so the name and the answer arrive together.
+budget_rate() {
+  local connector="${1:-}" account="${2:-}" bucket="${3:-}" now="${4:-}"
+
+  # A caller that named a moment is asking a different question. Straight
+  # through, neither read nor written.
+  if [ -n "$now" ]; then
+    budget_rate_read "$connector" "$account" "$bucket" "$now"
+    return $?
+  fi
+
+  local key slot
+  key="${connector}|${account}|${bucket}"
+  # Every character a variable name may not hold becomes `_`. Two distinct
+  # triples could collide only by differing in punctuation alone, which no
+  # connector, account or bucket name does.
+  slot="_budget_rate_memo_$(printf '%s' "$key" | LC_ALL=C tr -c '[:alnum:]_' '_')"
+
+  # TIER ONE, FREE: the same shell asking twice. SET, NOT NON-EMPTY — the zero
+  # object is a real answer and an empty one is a state this memo never stores.
+  if eval "[ -n \"\${${slot}+set}\" ]"; then
+    eval "printf '%s\\n' \"\${${slot}}\""
+    return 0
+  fi
+
+  # TIER TWO, 82 us: a subshell asking what its parent already asked. This is
+  # the tier that fires at every call site `plot-host.sh` actually has.
+  local dir file answer
+  dir="$(budget_memo_dir)" || dir=''
+  if [ -n "$dir" ]; then
+    file="$dir/$slot"
+    # `-s`, NOT `-f`. A zero-byte entry is a torn write, never an answer.
+    if [ -s "$file" ]; then
+      IFS= read -r answer < "$file" 2>/dev/null || answer=''
+      if [ -n "$answer" ]; then
+        eval "${slot}=\$answer"
+        printf '%s\n' "$answer"
+        return 0
+      fi
+    fi
+  fi
+
+  local rc
+  # THE EXIT CODE IS THE READ'S, never this wrapper's. `budget_rate_read`
+  # returns 0 on every path today and its callers test the CONTENT, so a memo
+  # that invented an exit status would be the one place the two disagree.
+  answer="$(budget_rate_read "$connector" "$account" "$bucket")"; rc=$?
+  if [ "$rc" -ne 0 ]; then
+    # A read that failed is not an answer, so nothing is remembered: the next
+    # caller asks again rather than inheriting a failure for the process life.
+    printf '%s\n' "$answer"
+    return "$rc"
+  fi
+  eval "${slot}=\$answer"
+  # NEVER FAILS ITS CALLER, `budget_append`'s rule for the same reason: the memo
+  # is an optimisation beside an answer that is already correct, so a cache that
+  # cannot be written must not turn a good reading into a failed one.
+  if [ -n "$dir" ] && mkdir -p "$dir" 2>/dev/null; then
+    if printf '%s\n' "$answer" >"$file.$BASHPID.tmp" 2>/dev/null; then
+      mv -f "$file.$BASHPID.tmp" "$file" 2>/dev/null || rm -f "$file.$BASHPID.tmp" 2>/dev/null || true
+    fi
+  fi
+  printf '%s\n' "$answer"
+  return 0
+}
+
+# Where THIS PROCESS's memoised rates live, and it is deliberately not beside
+# the record. `$PLOT_BUDGET_HOME/memo/<pid>` — same override as the record and
+# the slots, so a test pointing `PLOT_BUDGET_HOME` at a sandbox gets a sandboxed
+# cache too, and a `$PLOT_BUDGET_HOME` that cannot be resolved means no cache
+# rather than a cache in the wrong place.
+#
+# `$$` IS THE DIRECTORY NAME because it is the one identifier that is stable
+# across a command substitution — see `budget_rate` above, where that property
+# is the whole reason this file exists. A pid is reused by the kernel after the
+# process ends, so an entry could in principle be inherited by a later,
+# unrelated process holding the same pid. That is bounded by `budget_memo_clear`
+# below, which the adapter calls on exit, and it is why the cache holds a
+# DERIVED reading rather than anything a caller could act on irreversibly: the
+# worst case is one stale rate, which is the same staleness the memo grants
+# within a process by design.
+budget_memo_dir() {
+  local home="${PLOT_BUDGET_HOME:-}"
+  if [ -z "$home" ]; then
+    [ -n "${HOME:-}" ] || return 1
+    home="$HOME/.plot/state"
+  fi
+  printf '%s\n' "$home/memo/$$"
+}
+
+# Removes this process's memo directory. Called on exit by the adapter, so a
+# long-lived machine does not accumulate one directory per `plot-host.sh` call.
+#
+# NEVER FAILS ITS CALLER. It runs in a trap beside work that has already
+# happened, and a cache that cannot be cleared must not change an exit status.
+budget_memo_clear() {
+  local dir
+  dir="$(budget_memo_dir)" || return 0
+  case "$dir" in
+    */memo/[0-9]*) rm -rf "$dir" 2>/dev/null || true ;;
+  esac
+  return 0
+}
+
 # ── The concurrency bound ────────────────────────────────────────────────────
 #
 # HOW MANY CALLS THIS ACCOUNT HAS OPEN AT ONCE, bounded across PROCESSES. The

package/plot-deliver.sh

@@ -425,9 +425,15 @@ decide_transition() { # $1=file  → prints "<Phase>\t<record>\t<write|already>"
 # carrying BOTH front matter and a `## Status` block was delivered in a project
 # repo: `flip_phase` wrote `Delivered` into the block, `mv` landed it, the
 # summary said `phase=flipped`, and `plot-plan-meta.sh` went on answering
-# `approved` — because it prefers front matter wherever it exists and reads the
-# block only in the `else if` below. The write took effect on bytes nobody
-# reads.
+# `approved` — because it preferred front matter wherever it existed. The write
+# took effect on bytes nobody reads.
+#
+# THAT PRECEDENCE INVERTED IN #933, so the two-record plan now delivers rather
+# than refusing here: the parser reads the `## Status` block, which is the field
+# every lifecycle script writes. This gate is unchanged and is not softened —
+# its condition simply stops holding for that shape. It still fires on a scratch
+# copy the parser cannot read, and it still asks the parser rather than trusting
+# that awk changed a line.
 #
 # `flip_phase`'s awk matches only inside `section == "status"`. That one guard
 # IS the defect: on a front-matter plan it edits the block and leaves the front
@@ -468,11 +474,11 @@ phase_would_read() { # $1=scratch file $2=expected phase (lowercase) → 0 agree
   # holding two records of one fact is the thing to fix — and which format ought
   # to win is a decision this gate deliberately leaves to a person.
   echo "plot-deliver: $rel — wrote phase '$want', but the parser still reads '$got'." >&2
-  echo "  The plan states its phase in TWO places and they disagree: the write" >&2
-  echo "  landed in the '## Status' block while front matter takes precedence," >&2
-  echo "  so the delivery would have reported a success it did not achieve." >&2
-  echo "  Nothing was written — the plan is unchanged. Remove one of the two" >&2
-  echo "  records (front matter, or the '## Status' block) and re-run." >&2
+  echo "  The write landed and the parser reads something else, so the delivery" >&2
+  echo "  would have reported a success it did not achieve." >&2
+  echo "  Nothing was written — the plan is unchanged. Check what the plan says" >&2
+  echo "  its phase is, and where: a plan stating it in two places reports the" >&2
+  echo "  '## Status' block, which is the field every lifecycle script writes." >&2
   echo "  See what the parser reads: $script_dir/plot-plan-meta.sh $rel" >&2
   return 1
 }

package/plot-dispatch.sh

@@ -1904,62 +1904,70 @@ EOF
     esac
   fi
 
-  # THE COUNT IS THE RULE'S, and the rule is `packages/domain/src/rules/
-  # fleet-size.ts` — imported directly, the same shape `plot-reap.sh` uses for
-  # `reapable.ts`. Node 24 strips the types, so there is no build step between
-  # this script and the decision it asks for, and there is no second copy of the
-  # default, the subtraction or the machine's veto living in shell.
-  #
-  # A RULE THAT CANNOT BE ASKED STARTS NOTHING AND SAYS SO. Missing node, a
-  # failed import, a module that throws all leave the answer empty. The
-  # direction is the reaper's: silence is never permission, and here permission
-  # would spawn detached processes.
+  # THE COUNT IS THE RULE'S, and the rule is asked through its BUNDLE —
+  # `board/plot-fleet-size.mjs`, tracked in git beside the other 24. There is no
+  # second copy of the default, the subtraction or the machine's veto living in
+  # shell.
+  #
+  # A SOURCE IMPORT CANNOT REACH A PLUGIN INSTALL, and this block used to be
+  # one. It imported `rules/fleet-size.ts` and `entities/machine.ts` as `file://`
+  # sources. Node 24 strips types, so the TypeScript was never the obstacle — the
+  # SECOND import is: `machine.ts` opens with `import { z } from 'zod'`, and an
+  # install carrying no `node_modules` cannot resolve it. Measured 2026-09-17
+  # against a copy with no `node_modules` on the path:
+  #
+  #   machine.ts FAILED: Cannot find package 'zod'
+  #   fleet-size.ts: imported
+  #
+  # So the bundle carries BOTH rules with `zod` bundled in. `a-shell-script-asks
+  # -the-domain` settled the shape: a bundle under `skills/plot/scripts/board/`
+  # is how a shell script reaches a rule, and a skill's own script directory is
+  # what a plugin ships.
   #
   # TWO MODULES, BECAUSE THE VERDICT AND THE COUNT ARE TWO RULES. `headroomFor`
   # owns what a fork cost MEANS and `fleetSize` owns what to do about it; the
   # count rule takes the verdict as a reading rather than deriving it, so the
-  # thresholds have exactly one home and this block is the join.
-  #
-  # IMPORTED AS `.ts` WITH NO `.js` REWRITING. Node 24 strips types but does not
-  # remap a relative specifier, so `fleet-size.ts` may only `import type` from
-  # its neighbours — which is why the verdict arrives as a value here rather
-  # than being computed inside the rule.
-  start_domain="$(cd "$script_dir/../../.." 2>/dev/null && pwd)/packages/domain/src"
-  start_rule="file://$start_domain/rules/fleet-size.ts"
-  start_answer=$(PLOT_REQUESTED="$start_count" PLOT_RUNNING="$start_running" \
-                 PLOT_COST="$start_cost" PLOT_RULE="$start_rule" \
-                 PLOT_MACHINE="file://$start_domain/entities/machine.ts" \
-                 node --input-type=module - <<'NODE_EOF' 2>/dev/null
-const { fleetSize, DEFAULT_FLEET_SIZE } = await import(process.env.PLOT_RULE);
-const { headroomFor } = await import(process.env.PLOT_MACHINE);
-
-// AN ABSENT COUNT IS THE RULE'S DEFAULT, resolved here rather than in the
-// shell: the number and the argument for it have one home.
-const requested =
-  process.env.PLOT_REQUESTED === "" ? DEFAULT_FLEET_SIZE : Number(process.env.PLOT_REQUESTED);
-
-// An UNMEASURED cost is null, never zero: zero is the fastest fork there is and
-// would read as the clearest possible machine.
-const spawnCostMs = process.env.PLOT_COST === "" ? null : Number(process.env.PLOT_COST);
-
-const answer = fleetSize({
-  requested,
-  running: Number(process.env.PLOT_RUNNING),
-  spawnCostMs,
-  headroom: headroomFor(spawnCostMs),
-});
-
-process.stdout.write(`${answer.start}\t${answer.headroom}\t${answer.shortfall}`);
-NODE_EOF
-  )
+  # thresholds have exactly one home and the bundle's entry is the join.
+  #
+  # A RULE THAT CANNOT BE ASKED STARTS NOTHING AND SAYS SO. A missing bundle, a
+  # missing node, a module that throws all leave the answer empty. The direction
+  # is the reaper's: silence is never permission, and here permission would spawn
+  # detached processes.
+  start_bundle="$script_dir/board/plot-fleet-size.mjs"
+  start_answer=$(printf '%s\t%s\t%s' "$start_count" "$start_running" "$start_cost" \
+                 | node "$start_bundle" 2>/dev/null)
 
   if [ -z "$start_answer" ]; then
+    # THE REFUSAL NAMES THE CONDITION THAT FAILED, never two that hold. The
+    # message this replaced said *"it needs node 24 and a readable checkout of
+    # packages/domain"* to an operator whose node was 24.4.1 and whose checkout
+    # was readable — the import it could not resolve was named nowhere. A
+    # refusal that names the wrong condition costs more than one that says
+    # nothing, because it looks actionable. So the two causes are separated and
+    # tested in the order that distinguishes them: an absent bundle is a broken
+    # or partial installation, and a present bundle that answered nothing is the
+    # runtime underneath it.
     echo "plot-dispatch: --start could not ask how many agents to start — starting none." >&2
-    echo "  The rule is $start_rule" >&2
-    echo "  It needs node 24 and a readable checkout of packages/domain." >&2
+    if [ ! -f "$start_bundle" ]; then
+      echo "  The rule's bundle is missing: $start_bundle" >&2
+      echo "  Every bundle is tracked in git, so this is a broken or partial installation." >&2
+      echo "  In a development checkout, run 'pnpm build:board'." >&2
+    else
+      start_node_v="$(node --version 2>/dev/null)" || start_node_v=""
+      echo "  The rule's bundle is $start_bundle" >&2
+      if [ -z "$start_node_v" ]; then
+        echo "  No usable 'node' was found on PATH. The bundle needs node 20 or newer." >&2
+      else
+        echo "  The bundle is present but answered nothing under node $start_node_v." >&2
+        echo "  Run it directly to see why: printf '%s\\t%s\\t%s' '$start_count' '$start_running' '$start_cost' | node '$start_bundle'" >&2
+      fi
+    fi
     exit 1
   fi
 
+  # THREE FIELDS, AND THE SENTENCE IS LAST. `start_why` is printed to the
+  # operator below, so it travels; taking it as the whole remainder means a
+  # shortfall can never be truncated by its own punctuation.
   start_n=${start_answer%%$'\t'*}
   start_rest=${start_answer#*$'\t'}
   start_headroom=${start_rest%%$'\t'*}

package/plot-fleet-scan.sh

@@ -89,6 +89,9 @@
 # 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
+#         `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.
 #         merge_detect names how merged-and-deleted branches were detected:
@@ -631,6 +634,19 @@ PR_LIST_LIMIT="${PLOT_PR_LIST_LIMIT:-1000}"
 #   secondary  — a burst refusal (`plot-host.sh` exit 6). Nothing is broken
 #                either, and it clears in seconds rather than minutes.
 #   failed     — any other failure (exit 3, or anything unclassified).
+#   partial    — SOME of the host's states answered and some did not
+#                (`plot-host.sh` exit 7). The rows that arrived are real and
+#                are parsed; what is missing is a whole state, so the reading
+#                is incomplete rather than absent. Only Bitbucket can produce
+#                it: `bb pr list` has no `all` state, so the arm asks once per
+#                state, while GitHub takes `--state all` in one call.
+#
+#                IT IS NOT `ok` AND IT IS NOT `failed`. Reporting `ok` would
+#                serve a page missing a state as a complete answer — #912, where
+#                nine branches read `commits, no PR ever opened` and two had
+#                live PRs. Reporting `failed` would throw away rows that
+#                arrived and make every branch `unknown`, which is not
+#                startable — the right refusal about the wrong thing.
 #   unasked    — no host to ask, or --offline WITHOUT `--next`. Not a
 #                degradation: the scan was never going to ask, and saying
 #                `failed` would report a fault where there is a configuration.
@@ -644,6 +660,43 @@ PR_LIST_LIMIT="${PLOT_PR_LIST_LIMIT:-1000}"
 # secondary limit waits minutes for a ceiling that cleared in seconds.
 HOST_VERDICT=unasked
 
+# The remote branches this scan tracks, read once for every question that asks.
+#
+# MOVED UP FROM ITS OLD POSITION (#333) so the host call below can be told which
+# branches to ask about. It is the same single `for-each-ref` it always was —
+# see the commentary at its old site — and the reasons it exists are unchanged:
+# `git show-ref --verify` was asked once per branch from two places, and
+# `%(objectname)` rides along free for the commit walk.
+REMOTE_REFS=$(git for-each-ref --format='%(refname:strip=3)%09%(objectname)' \
+  "refs/remotes/origin" </dev/null 2>/dev/null)
+
+# The branch names alone, space-separated — what the sweep asks the host about.
+#
+# THE JOIN'S OWN KEYS, AND NOTHING WIDER. `prefill_pr_states` indexes the host's
+# reply by branch and every row it cannot key is discarded, so the set this asks
+# about is exactly the set that could ever be used. Measured 2026-09-20 on
+# `quatico/quaweb-website`: 11 remote branches against 902 pull requests, of
+# which a listing hands over 50 — the sweep asks 11 questions and gets 11
+# answers, where the listing asked one and answered for 5%.
+#
+# `HEAD` IS DROPPED. `refs/remotes/origin/HEAD` is a symbolic ref naming the
+# default branch, not a branch of its own; asking the host about a branch called
+# `HEAD` spends a query to learn that nothing is named that.
+#
+# SPACE-SEPARATED, AND GIT IS WHAT MAKES THAT SAFE. Both this list and the
+# adapter's `PR_LIST_BRANCHES` are read by an unquoted `for`, so a name carrying
+# whitespace would split into two branches that do not exist. `git
+# check-ref-format` REFUSES a ref name containing a space or a tab — verified
+# 2026-09-20, both exit non-zero — so no such branch can reach this, and the
+# separator is git's guarantee rather than a hopeful convention.
+#
+# EMPTY IS A REAL ANSWER AND IT DISABLES THE SWEEP. A checkout with no remote
+# refs has no branches to ask about, and a sweep of nothing would state that
+# every tracked branch answered — a completeness claim over an empty set, which
+# would license `NONE` for branches nobody asked about. `prefill_pr_states`
+# 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
@@ -672,10 +725,34 @@ prefill_pr_states() {
   # 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)
-  if [ "$rc" -ne 0 ]; then
+  # 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
+  # is nothing to read. Here there is — the rows of the states that answered are
+  # already in `host_list_out`, since stdout is redirected to a file and stderr
+  # captured separately.
+  #
+  # 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
     # 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
@@ -743,7 +820,12 @@ prefill_pr_states() {
     return 0
   fi
   # The list arrived. An empty one arrived too — that is the whole distinction.
-  HOST_VERDICT=ok
+  #
+  # 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
   # `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 —
@@ -864,9 +946,39 @@ EOF
   # A repository genuinely holding zero PRs loses nothing by being asked: it has
   # no branches with PRs for the join to serve either, so the cost is zero calls
   # in both readings.
-  if [ "$_pr_rows" -gt 0 ] && [ "$_pr_rows" -lt "$PR_LIST_LIMIT" ] 2>/dev/null; then
-    printf '1' > "$HOST_STATE_CACHE/.list-complete" 2>/dev/null || true
-  fi
+  #
+  # A SWEEP STATES ITS COMPLETENESS; A PAGE ONLY EVER IMPLIED IT (#333). The
+  # test above reads completeness off one page's size, which is the only
+  # evidence a listing offers — and on Bitbucket it is evidence the listing
+  # cannot give at all, since `bb pr list` returns a fixed 50 whether or not
+  # more exist. Where the adapter swept per branch it says so on stderr, naming
+  # both counts, and that sentence is a stronger claim than any row count: every
+  # tracked branch was asked and each one answered.
+  #
+  # THE ROW COUNT IS NOT CONSULTED ON THAT PATH, and it must not be. A sweep
+  # over 11 branches of which 2 have pull requests emits 2 rows — a true and
+  # complete answer that `0 < rows < PR_LIST_LIMIT` would also accept, but for
+  # the wrong reason, and which a sweep of 0 matches would fail outright despite
+  # being equally complete. Reading the claim the adapter made is exact where
+  # re-deriving it from the output is a coincidence.
+  #
+  # THE WORDING IS A CONTRACT between this script and `plot-host.sh`'s
+  # `pr_sweep_report`, pinned on both sides. A partial sweep never prints it, so
+  # a match is licence and a miss is silence — never a guess.
+  #
+  # WHAT IS LOST BY GETTING THIS WRONG IS COST, NOT CORRECTNESS. Without the
+  # marker, `host_pr_state --ask` falls through to one `pr-state` call per
+  # 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.
+  case "$host_err" in
+    *"pr-list sweep complete"*)
+      printf '1' > "$HOST_STATE_CACHE/.list-complete" 2>/dev/null || true ;;
+    *)
+      if [ "$_pr_rows" -gt 0 ] && [ "$_pr_rows" -lt "$PR_LIST_LIMIT" ] 2>/dev/null; then
+        printf '1' > "$HOST_STATE_CACHE/.list-complete" 2>/dev/null || true
+      fi ;;
+  esac
 }
 prefill_pr_states
 
@@ -1487,8 +1599,12 @@ worktree_locked() { # $1=worktree path → 0 when a lock is held there
 # on the population that must stay free. The walk here is a subject/emptiness
 # question rather than a timestamp read, but the guard is deliberately broad and
 # loosening it to fit this change is how a guard rots.
-REMOTE_REFS=$(git for-each-ref --format='%(refname:strip=3)%09%(objectname)' \
-  "refs/remotes/origin" </dev/null 2>/dev/null)
+# READ ABOVE `prefill_pr_states`, not here. The per-branch sweep (#333) hands
+# the host the branches this scan tracks, and that list is exactly what this
+# batch already answers — so the assignment moved up rather than a second
+# `for-each-ref` being added beside it. Everything documented above still
+# describes it; only the line's position changed, and it depends on nothing but
+# git, so nothing between the two points can read a different answer.
 
 # Whether `origin/$1` exists, answered from the batch rather than by spawning.
 #
@@ -4265,6 +4381,17 @@ elif [ "$HOST_VERDICT" = failed ]; then
   echo "        branch below reads from local evidence alone, and a branch whose"
   echo "        PR is unknown reads 'unknown' rather than 'open'. This is not a"
   echo "        rate limit — waiting will not clear it; check the host and auth."
+# THE PAGE IS SHORT, NOT ABSENT, and that is a different instruction to a
+# reader. The three notes above all say *no PR could be read*; here some were,
+# so the branches below are a MIXTURE — a branch shown without a PR may have one
+# in the state that failed. Telling a reader to treat this as an outage would
+# discard the rows that arrived; telling them nothing is #912, where nine
+# branches read as having no PR and two had live ones.
+elif [ "$HOST_VERDICT" = partial ]; then
+  echo "  note: the git host answered for some states and not others, so the PR"
+  echo "        list below is INCOMPLETE. A branch shown without a PR may have one"
+  echo "        in the state that failed — do not read this as evidence that a"
+  echo "        branch is unreviewed. Re-run to get the whole list."
 fi
 # A STALE PULSE SAYS SO. The fetch used to fail silently, which made a scan of
 # hour-old refs read exactly like a scan of current ones — the same