@plot-pm/board 0.14.1 → 0.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "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-deliver.sh

@@ -419,6 +419,70 @@ decide_transition() { # $1=file  → prints "<Phase>\t<record>\t<write|already>"
 # writes — and appending a second is how one plan came to hold two `Delivered:`
 # lines (2026-09-01). The domain returns the written record unchanged in that
 # case, so the phase still flips and nothing is inserted.
+# Would the PARSER read this phase out of the file we are about to land?
+#
+# THE WRITE SUCCEEDING IS NOT THE OUTCOME HOLDING, and that gap is #924. A plan
+# 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 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
+# matter untouched, and returns 0 for having changed something.
+#
+# SO THE TEST IS WHAT THE PARSER ANSWERS, NEVER WHETHER AWK CHANGED A LINE.
+# Refusing on `flipped=0` would break every re-run of a correct delivery — a
+# plan already carrying `Delivered` flips nothing and is fine. This asks the one
+# question that distinguishes them: read the scratch copy the way every later
+# consumer will read the plan, and compare.
+#
+# IT RUNS ON THE SCRATCH COPY, BEFORE THE `mv`, and the caller passes whichever
+# file that arm is about to land — `$a` on the `recorded=yes` arm, `$b` on the
+# other. Parsing `$a` on the record arm would check content that never reaches
+# the plan. After the `mv` is too late twice over: the script's own header
+# documents exit 0 as *"the plan is Delivered on the default branch"*, so
+# refusing there would exit 1 on a run meeting the documented success
+# condition — and `runAutoDeliver` spawns this detached, logging a non-zero exit
+# to nobody while the plan sits delivered on main.
+#
+# AN UNREADABLE SCRATCH COPY REFUSES. `decide_transition` already takes that
+# line — *"refusing rather than guessing"* — and a file the parser cannot read
+# is exactly the state this gate exists to keep off the plan.
+phase_would_read() { # $1=scratch file $2=expected phase (lowercase) → 0 agrees, 1 refuses
+  local scratch="$1" want="$2" m got
+  m=$(bash "$script_dir/plot-plan-meta.sh" "$scratch" 2>/dev/null) || m=""
+  if [ -z "$m" ]; then
+    echo "plot-deliver: $rel — the written file does not parse, so the delivery was not landed." >&2
+    echo "  Nothing was written. Re-run after fixing the file." >&2
+    return 1
+  fi
+  got=$(printf '%s' "$m" | jq -r '.phase // ""')
+  [ "$got" = "$want" ] && return 0
+
+  # THE REFUSAL NAMES BOTH VALUES AND THE FILE. A message saying only "delivery
+  # failed" throws away the half a person acts on: which phase was written, and
+  # which one the parser still reads. The cause is named too, because the file
+  # 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 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
+}
+
 write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_report record_report
   local f="$1" record="$2" recorded="$3" a="$1.plot-phase" b="$1.plot-record" flipped=0
 
@@ -428,6 +492,11 @@ write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_repo
   [ -s "$a" ] || { rm -f "$a"; echo "plot-deliver: could not read $rel" >&2; return 1; }
 
   if [ "$recorded" = "yes" ]; then
+    # THE DRY RUN, on the file this arm is about to land. A refusal discards the
+    # scratch copy and leaves the plan byte-identical — and never reaches
+    # `record_state_receipt`, which would otherwise license a commit of a state
+    # that was refused.
+    phase_would_read "$a" delivered || { rm -f "$a"; return 1; }
     mv "$a" "$f" || { rm -f "$a"; return 1; }
     record_report="already"
   else
@@ -438,6 +507,9 @@ write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_repo
       echo "  with no record is invisible to the scan. Fix the section and re-run." >&2
       return 1
     fi
+    # `$b` AND NOT `$a`: this arm lands the file carrying the record, so `$a`
+    # is content that never reaches the plan.
+    phase_would_read "$b" delivered || { rm -f "$a" "$b"; return 1; }
     mv "$b" "$f" || { rm -f "$a" "$b"; return 1; }
     rm -f "$a"
     record_report="written"

package/plot-dispatch.sh

@@ -56,6 +56,25 @@
 #               tradition of --allow-local: a gate with no exit is one people
 #               route around by never annotating at all. It says so on the
 #               line it overrides, so the override is on the record.
+#   --agent <name>  dispatch this run's agents under the charter
+#               `.plot/charters/<name>.json`. It SETS `PLOT_AGENT`, which was
+#               the input all along and which nothing chose: the charter
+#               mechanism shipped in v2.17.0 with 16 readers for `harness` and
+#               no selector at all, so a kind could be declared and never
+#               asked for. The choice is EXPLICIT and never inferred — a
+#               matcher reading a plan could guess a kind, and a guess that is
+#               usually right produces a fleet whose wrong answers cannot be
+#               explained. An already-exported PLOT_AGENT is overridden, since
+#               a flag on this run is the more specific answer.
+#               AMENDED 2026-09-15: a slice may now DECLARE its kind, and
+#               `start_worker` reads it where this flag left `PLOT_AGENT`
+#               unset. That is not the matcher refused above — a declaration is
+#               a field a person wrote, and nothing here ranks candidates or
+#               infers a kind from a slice's contents. The flag still wins,
+#               because a flag typed on this run is more specific than a field
+#               written when the plan was drafted. A charter this clone does
+#               not hold is REPORTED and dispatched anyway; see
+#               `plan_declared_agent`.
 #   <slug>      the plan to fan out
 # Output: one line per branch, each optionally followed by an indented
 #         `in flight:` line naming a branch that already holds files, then the
@@ -230,6 +249,7 @@ allow_waiting=0
 max=0
 slug=""
 migrate_yes=0
+agent=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --dry-run)  dry_run=1 ;;
@@ -270,17 +290,56 @@ while [ $# -gt 0 ]; do
     --offline|--no-fetch) offline="--offline" ;;
     --allow-local) allow_local=1 ;;
     --allow-waiting) allow_waiting=1 ;;
+    # THE VALUE IS REQUIRED AND ALWAYS CONSUMED, which is the opposite of the
+    # rule `--stop`, `--restart` and `--start` follow — and the difference is
+    # the value's SHAPE rather than a change of mind. Those three take a branch
+    # (`*/*`) or a count (digits), each recognisable on sight, so an absent one
+    # can be left for the parser. An agent name is a bare word and so is a plan
+    # slug: nothing tells `--agent reviewer` from `--agent` followed by the
+    # slug. Leaving it unconsumed would let the `*)` arm below silently take
+    # the agent name as the plan to dispatch, which reads as "no such plan" and
+    # names neither what was asked nor what went wrong. So a missing value
+    # REFUSES rather than guessing.
+    --agent)    agent="${2:?--agent needs a charter name, e.g. --agent reviewer}"
+                case "$agent" in
+                  -*) echo "plot-dispatch: --agent needs a charter name, got '$agent'" >&2; exit 1 ;;
+                esac
+                shift ;;
     --max)      max="${2:?--max needs a value}"
                 case "$max" in
                   ''|*[!0-9]*) echo "plot-dispatch: --max needs a number, got '$max'" >&2; exit 1 ;;
                 esac
                 shift ;;
-    -h|--help)  sed -n '2,59p' "$0"; exit 0 ;;
+    # THE RANGE MOVED WITH THE HEADER IT PRINTS. It ended at `<slug>` and still
+    # does; adding `--agent` above pushed that line from 59 to 69, and
+    # documenting the plan-declared kind pushed it from 69 to 78. Two records
+    # of one fact, and nothing compares them — a stale number here silently
+    # truncates the help rather than failing, so it is checked by a test.
+    -h|--help)  sed -n '2,78p' "$0"; exit 0 ;;
     *)          slug="$1" ;;
   esac
   shift
 done
 
+# `--agent` SETS THE INPUT THAT ALREADY EXISTED, and it sets it in ONE place.
+#
+# `PLOT_AGENT` was read in three places before this flag — `resolve_launch`'s
+# call in `start_worker`, the `--capabilities` block, and the forwarded export
+# into the worker's environment — and assigned in none: `plot-dispatch.sh` held
+# `PLOT_AGENT="${PLOT_AGENT:-}"`, a pass-through of whatever the operator had
+# already exported. So the selector existed as a variable nothing chose.
+#
+# ONE ASSIGNMENT RATHER THAN A THREADED ARGUMENT. Every reader already asks
+# `${PLOT_AGENT:-}`; exporting here reaches all three with no further change and
+# leaves no call site that could be missed when a fourth reader is added. The
+# flag's whole meaning is "set PLOT_AGENT", which is also what keeps it from
+# becoming a second selector competing with the variable.
+#
+# THE FLAG WINS OVER AN INHERITED VALUE. A dispatched worker runs with its own
+# `PLOT_AGENT` in the environment, so a run launched from inside one would
+# otherwise inherit a kind nobody asked for on this dispatch.
+[ -n "$agent" ] && export PLOT_AGENT="$agent"
+
 # THE TWO PRECONDITIONS OF A DISPATCH, and a sourcing test has neither.
 # `PLOT_DISPATCH_SOURCED=1` is taking the definitions below rather than running
 # a dispatch, so it has no slug and often no git repository; the guard that
@@ -930,6 +989,42 @@ start_worker() {
   local branch="$1" wt="$2"
   local cmd
 
+  # THE PLAN IS THE DEFAULT AND THE FLAG IS THE OVERRIDE.
+  #
+  # `[ -z "${PLOT_AGENT:-}" ]` is the whole precedence rule: `--agent` exported
+  # the variable before this line was reached, so a flag typed on this run stops
+  # the plan being read at all. A field written when the plan was drafted is the
+  # less specific answer — the same order `--agent` already applies to an
+  # inherited `PLOT_AGENT`.
+  #
+  # ONE ASSIGNMENT, FOR THE REASON `--agent` GIVES ONE FIELD OVER. Four readers
+  # ask `${PLOT_AGENT:-}` — `resolve_launch` below, the capabilities block, the
+  # manifest, and the export into the worker environment — so setting the
+  # variable reaches all four and leaves no call site to miss when a fifth
+  # appears.
+  #
+  # A FREE AGENT HAS NO BRANCH and so has no plan to read: `--start` calls this
+  # with `branch` empty, and `plan_declared_agent` returns 1 on it immediately.
+  if [ -z "${PLOT_AGENT:-}" ] && [ -n "$branch" ]; then
+    local declared charter
+    if declared=$(plan_declared_agent "$branch"); then
+      export PLOT_AGENT="$declared"
+      # A MISSING CHARTER IS REPORTED AND DISPATCHED ANYWAY. Said HERE rather
+      # than only in the manifest, because this is where a person watching the
+      # run can still act on it: the launch below falls back to the repo default
+      # and is otherwise silent about a declaration that reached nothing.
+      charter=$(charter_file_for "$declared")
+      if [ -n "$charter" ] && [ ! -f "$charter" ]; then
+        echo "    $branch declares agent '$declared', and no charter answers to that name"
+        echo "      looked for $charter"
+        echo "      starting it on the repo's 'Worker command' — a plan written where that"
+        echo "      charter exists must stay dispatchable on a clone that lacks it."
+      else
+        echo "    $branch declares agent '$declared' — its plan selected the charter"
+      fi
+    fi
+  fi
+
   # RESOLVED BEFORE `Worker command`, because the charter is the more specific
   # answer and the config key is the fallback rather than the sole source.
   #
@@ -1359,6 +1454,78 @@ start_worker() {
   return 0
 }
 
+# WHICH KIND OF AGENT A BRANCH'S PLAN DECLARES — the selector nobody has to type.
+#
+# `--agent` was the only one, and an operator is the only thing that can type a
+# flag. The registry hands a queued slice to a free agent with no `--agent`
+# anywhere in the path, so an unattended fleet ran every slice as the same
+# undifferentiated worker. A plan that names the kind is what reaches a dispatch
+# nobody is watching.
+#
+# IT ANSWERS AND EXPORTS NOTHING. The caller decides, because the precedence is
+# the caller's: `--agent` already won over an inherited `PLOT_AGENT` and must win
+# over this too — a flag typed on this run is more specific than a field written
+# when the plan was drafted.
+#
+# THE PLAN DIRECTORY IS SEARCHED, NOT THE ACTIVE INDEX, and the candidates are
+# grepped before any is parsed — both `plot-open-pr.sh`'s rules, measured there:
+# a plan governing a branch may carry no symlink, and parsing 253 plans took
+# 103 s against 0.6 s for one `grep -lF` over the directory. A branch name is a
+# literal string, so a plan that does not contain it cannot name it.
+#
+# ABSENCE IS THE COMMON ANSWER AND NEVER AN ERROR. Every plan on the estate
+# names no kind, a `--restart` may run on a branch no plan names at all, and the
+# annotation is optional by design. All three print nothing and return 1.
+plan_declared_agent() { # $1 = branch → prints the declared kind, or nothing
+  local branch="$1" plan_dir root cands f found
+  [ -n "$branch" ] || return 1
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || return 1
+  plan_dir=$("$script_dir/plot-config.sh" get "Plan directory" "docs/plans/")
+  case "$plan_dir" in /*) ;; *) plan_dir="$root/$plan_dir" ;; esac
+
+  cands=$(grep -lF "$branch" "$plan_dir"*.md 2>/dev/null || true)
+  for f in $cands; do
+    [ -e "$f" ] || continue
+    # The PARSER answers, never a grep of the plan file. A `grep agent:` would
+    # read the marker out of prose documenting it and out of a DIFFERENT branch
+    # line in the same plan — the annotation binds to one branch, and only the
+    # parser knows which.
+    found=$(bash "$script_dir/plot-plan-meta.sh" "$f" 2>/dev/null \
+      | PLOT_WANT_BRANCH="$branch" node -e '
+        let s = "";
+        process.stdin.on("data", (d) => (s += d)).on("end", () => {
+          let meta;
+          try { meta = JSON.parse(s); } catch { return; }
+          const want = process.env.PLOT_WANT_BRANCH;
+          for (const wave of meta.waves ?? []) {
+            for (const b of wave.branches ?? []) {
+              // PRESENCE, not truthiness. The parser emits no `agent` key where
+              // the plan declares none, which is every plan on the estate.
+              if (b.branch === want && "agent" in b) { console.log(b.agent); return; }
+            }
+          }
+        });
+      ') || found=""
+    if [ -n "$found" ]; then printf '%s\n' "$found"; return 0; fi
+  done
+  return 1
+}
+
+# DOES THIS CLONE HOLD THE CHARTER? Answered so a MISSING one can be REPORTED.
+#
+# A DELIBERATE ASYMMETRY, and the plan settles it: `resolve_launch` refuses a
+# charter it cannot BELIEVE (malformed) and a harness not on PATH, and both
+# stay. A charter that simply does not EXIST is the adoption case — a plan
+# written where `reviewer` is declared, dispatched on a clone that declares
+# nothing — and refusing it would make that plan undispatchable on every such
+# clone. So the kind still travels, the launch falls back to the repo default,
+# and the run SAYS which name it looked for.
+charter_file_for() { # $1 = agent name → prints the path it would read
+  local name="$1" root
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || return 1
+  printf '%s/.plot/charters/%s.json\n' "$root" "$name"
+}
+
 # `PLOT_DISPATCH_SOURCED=1` STOPS HERE, so a test can take `resolve_launch` and
 # `start_worker` without dispatching anything — `plot-worker-loop.sh` states
 # this idiom for `resolve_prompt_file`, and this is the same one applied to the
@@ -1737,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.
+  # 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:
   #
-  # 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.
+  #   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