@plot-pm/board 0.16.1 → 0.16.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
     "plot-config.sh",
     "plot-default-branch.sh",
     "plot-deliver.sh",
+    "plot-desk-root.sh",
     "plot-dispatch.sh",
     "plot-fleet-scan.sh",
     "plot-host.sh",

package/plot-approve.sh

@@ -128,7 +128,13 @@ git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository — run thi
 cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
 
 repo_root=$(git rev-parse --show-toplevel)
-wt_root=$(cd "$repo_root/.." && pwd)
+# The booking worktree goes under the desk root of the MAIN checkout, never of
+# this tree: inside a desk `--show-toplevel` answers the desk, and the default
+# `.worktrees` would resolve beneath it. No fallback — `plot-desk-root.sh`.
+# shellcheck source=plot-desk-root.sh
+. "$script_dir/plot-desk-root.sh"
+main_root=$(plot_repo_root)
+wt_root=$(plot_desk_root "$main_root") || die "cannot resolve where the booking worktree goes (see above)"
 
 PLAN_DIR=$(cfg "Plan directory" "docs/plans/")
 ACTIVE_DIR=$(cfg "Active index" "docs/plans/active/")
@@ -735,6 +741,9 @@ else
 
   bookbr="plot/approve-$slug"
   tmpwt="$wt_root/.plot-approve-$slug.$$"
+  # `git worktree add` creates the desk root when it is missing, so exclude it
+  # first: a booking run must not leave `.worktrees/` untracked in `git status`.
+  plot_exclude_desk_root "$main_root"
   # -B: a leftover branch from an earlier failed run must not block this one.
   # It is disposable by construction — created here, pushed, deleted.
   git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null \

package/plot-config.sh

@@ -27,12 +27,7 @@
 #   Project board | Branch prefixes | Plan directory | Active index |
 #   Delivered index | Sprint directory | Story directory | Story index |
 #   Plan template | Worker prompt template | Main branch | Board command
-#   Worktree root       where /plot-dispatch puts its worktrees. Read by
-#                       plot-dispatch.sh; default is the repo's PARENT, which
-#                       scatters `plot-wt-*` beside the checkout. An absolute
-#                       path is taken as given; a relative one resolves against
-#                       the repo root, so `.worktrees` gathers them inside it.
-#                       The default is kept for repos that never set it.
+#   Worktree root       the desk root; see its entry under the agent keys below.
 #   Worker bound        seconds a single prompt run may take in the worker loop
 #                       before it is ended and the worker exits (no hop). Read by
 #                       plot-worker-loop.sh; default 3600 (~1h), `0` disables it.
@@ -99,14 +94,15 @@
 #                       project-owned and reviewed like this one.
 #                       Absent or empty = no change, so an adopting project that
 #                       sets nothing behaves exactly as today.
-#   Worktree root       where /plot-dispatch creates fleet worktrees. A relative
-#                       value resolves against the repo root, an absolute one is
-#                       taken as given. Absent = the default `repo_root/..` with
-#                       the `plot-wt-` prefix — today's behaviour, so no existing
-#                       checkout moves. Under a dedicated root the prefix is
-#                       dropped: the directory already says these are Plot's. Read
-#                       only by the CREATION path; every "which worktree holds this
-#                       branch" read asks `git worktree list` instead.
+#   Worktree root       the desk root: where /plot-dispatch creates fleet
+#                       worktrees and the board writes its action records. A
+#                       relative value resolves against the MAIN checkout, an
+#                       absolute one is taken as given. Absent or empty =
+#                       `<repo>/.worktrees`. The rule is `deskRoot`, asked through
+#                       `plot-desk-root.sh`; no script resolves it itself. Desks
+#                       carry no prefix; `plot-wt-*` desks an older dispatch made
+#                       beside the repo stay there. Every "which worktree holds
+#                       this branch" read asks `git worktree list` instead.
 # Agent-runner keys (optional; Plot hardcodes no agent tooling, Principle 5):
 #   Worker command      how /plot-dispatch runs an agent headless on a worktree.
 #                       /plot-init writes `PLOT_UNATTENDED=1 plot-worker-loop.sh`;

package/plot-deliver.sh

@@ -81,7 +81,13 @@ git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository — run thi
 cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
 
 repo_root=$(git rev-parse --show-toplevel)
-wt_root=$(cd "$repo_root/.." && pwd)
+# The booking worktree goes under the desk root of the MAIN checkout, never of
+# this tree: inside a desk `--show-toplevel` answers the desk, and the default
+# `.worktrees` would resolve beneath it. No fallback — `plot-desk-root.sh`.
+# shellcheck source=plot-desk-root.sh
+. "$script_dir/plot-desk-root.sh"
+main_root=$(plot_repo_root)
+wt_root=$(plot_desk_root "$main_root") || die "cannot resolve where the booking worktree goes (see above)"
 
 PLAN_DIR=$(cfg "Plan directory" "docs/plans/")
 ACTIVE_DIR=$(cfg "Active index" "docs/plans/active/")
@@ -635,6 +641,9 @@ git fetch -q origin "$MAIN" 2>/dev/null
 
 bookbr="plot/deliver-$slug"
 tmpwt="$wt_root/.plot-deliver-$slug.$$"
+# `git worktree add` creates the desk root when it is missing, so exclude it
+# first: a booking run must not leave `.worktrees/` untracked in `git status`.
+plot_exclude_desk_root "$main_root"
 # -B: a leftover branch from an earlier failed run must not block this one.
 git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null \
   || die "could not prepare a booking worktree at $tmpwt.

package/plot-desk-root.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# The ONE answer to "where do desks and action records go?" — sourced, not run.
+#
+# Every script that resolved this privately asks here instead. Nine sites
+# computed the rule on 2026-10-01 and two of them already answered `.worktrees`
+# while seven answered the checkout's parent, so one of the two populations was
+# always writing somewhere the other did not read.
+#
+# The rule itself is `deskRoot` in the domain, asked through
+# `board/plot-desk-root.mjs`, per *A Shell Script Asks The Domain*: every caller
+# runs once per operator command, which is the cost rule's permitted case.
+#
+# NO CALLER KEEPS A FALLBACK DEFAULT. When the bundle cannot answer — no `node`,
+# a missing file — the caller stops with the reason. A silent fallback is a
+# second default, and two defaults are the defect this removes.
+#
+#   plot_repo_root            → the MAIN checkout, from anywhere
+#   plot_desk_root [repo [configured]] → the desk root; exit 3 when unaskable
+#   plot_exclude_desk_root [repo] → keep it out of `git status`; never fails
+#
+# shellcheck shell=bash
+
+# The MAIN checkout, from a desk as readily as from the checkout itself.
+#
+# `--show-toplevel` answers the DESK inside a linked worktree, so with
+# `.worktrees` as the default it would resolve `<desk>/.worktrees` and place
+# every tree under a root nothing else reads. `plot-reap.sh:440-447` recorded
+# that failure on 2026-09-10, when every tree read as unplaceable.
+#
+# The parent of `--git-common-dir` is the main checkout from anywhere, because
+# every linked worktree shares that one directory. It is asked FIRST and
+# `--show-toplevel` is the fallback, since the common dir is also correct in a
+# non-worktree checkout: there `.git` is a real directory in the root.
+#
+# PHYSICAL, through `pwd -P`: `git worktree list` and `--show-toplevel` print
+# resolved paths, and a desk root composed from a logical one (`/tmp` against
+# `/private/tmp` on macOS) is a prefix no worktree path ever starts with.
+plot_repo_root() {
+  local common root=''
+  common=$(git rev-parse --git-common-dir 2>/dev/null) && [ -n "$common" ] && {
+    common=$(cd -- "$common" 2>/dev/null && pwd -P) || common=''
+    [ -n "$common" ] && root=$(dirname -- "$common")
+  }
+  [ -n "$root" ] || root=$(git rev-parse --show-toplevel 2>/dev/null) || root=$(pwd)
+  printf '%s\n' "$root"
+}
+
+# Resolved ONCE at source time, the way `plot-pr-merged.sh:105` resolves its
+# own bundle. Computing it inside a function reads `BASH_SOURCE[0]` at call
+# time, which is the caller's file once the function has been exported.
+_plot_desk_root_mjs="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/board/plot-desk-root.mjs"
+_plot_desk_root_config="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/plot-config.sh"
+
+# The desk root for a repository, or exit 3 with the reason on stderr.
+#
+# A second argument is a value the caller was handed in place of the key — a
+# `--worktrees DIR` flag — and goes through the same rule; without one the
+# `Worktree root` key is read.
+#
+# READ THE EXIT CODE. A caller that treats an empty answer as a location would
+# compose paths against the filesystem root.
+plot_desk_root() {
+  local repo="${1:-}" bundle="$_plot_desk_root_mjs" configured answer
+  [ -n "$repo" ] || repo=$(plot_repo_root)
+  if [ ! -f "$bundle" ]; then
+    printf 'plot: cannot resolve the desk root: %s is missing\n' "$bundle" >&2
+    return 3
+  fi
+  if [ "$#" -ge 2 ]; then
+    configured="$2"
+  else
+    # Read from the TARGET repository, never the ambient one: `plot-config.sh`
+    # walks up from its cwd, so a caller asking about another checkout would
+    # otherwise get this one's key.
+    # A read that fails is a refusal, never the absent row: reading it as empty
+    # would answer the default for a repository that configured another root.
+    configured=$(cd -- "$repo" 2>/dev/null && bash "$_plot_desk_root_config" get "Worktree root" "" 2>/dev/null) || {
+      printf 'plot: cannot resolve the desk root: the Worktree root key in %s could not be read\n' "$repo" >&2
+      return 3
+    }
+  fi
+  answer=$(node "$bundle" "$repo" "$configured" 2>&1) || {
+    printf 'plot: cannot resolve the desk root: %s\n' "$answer" >&2
+    return 3
+  }
+  [ -n "$answer" ] || {
+    printf 'plot: the desk root rule answered nothing for %s\n' "$repo" >&2
+    return 3
+  }
+  printf '%s\n' "$answer"
+}
+
+# Keep the desk root out of `git status`, when it lies inside the repository.
+#
+# The line goes into the COMMON git directory's `info/exclude`: git reads that
+# file from the common directory only, so a linked worktree's private gitdir is
+# the wrong place and a desk writing there would exclude nothing. The write is
+# idempotent, and `info/exclude` is never committed.
+#
+# Called by whoever CREATES the directory. Best-effort and always exit 0: a
+# failure leaves untracked files in a listing, which is untidy, while refusing
+# to create a desk over it would stop the work.
+plot_exclude_desk_root() {
+  local repo="${1:-}" bundle="$_plot_desk_root_mjs" line common exclude configured
+  [ -n "$repo" ] || repo=$(plot_repo_root)
+  [ -f "$bundle" ] || return 0
+  configured=$(cd -- "$repo" 2>/dev/null && bash "$_plot_desk_root_config" get "Worktree root" "" 2>/dev/null) || configured=''
+  line=$(node "$bundle" --exclude-line "$repo" "$configured" 2>/dev/null) || return 0
+  # Empty means the root lies outside the repository, which needs no line.
+  [ -n "$line" ] || return 0
+  # Already ignored, by a `.gitignore` line /plot-init wrote or by an earlier
+  # run. A second rule for a path already ignored is noise in a file people read.
+  ( cd -- "$repo" 2>/dev/null && git check-ignore -q ".$line" ) && return 0
+  common=$(cd -- "$repo" 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null) || return 0
+  [ -n "$common" ] || return 0
+  case "$common" in /*) ;; *) common="$repo/$common" ;; esac
+  exclude="$common/info/exclude"
+  if [ -f "$exclude" ] && grep -qxF "$line" "$exclude" 2>/dev/null; then return 0; fi
+  mkdir -p "$common/info" 2>/dev/null || return 0
+  # A file not ending in a newline would otherwise join this line to its last.
+  if [ -s "$exclude" ] && [ "$(tail -c 1 "$exclude" 2>/dev/null)" != "" ]; then
+    printf '\n%s\n' "$line" >> "$exclude" 2>/dev/null || true
+  else
+    printf '%s\n' "$line" >> "$exclude" 2>/dev/null || true
+  fi
+  return 0
+}

package/plot-dispatch.sh

@@ -219,40 +219,37 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # WHERE THE WORKTREES LIVE, and by what name
 # ---------------------------------------------------------------------------
 #
-# Two facts, resolved together because the second is a PROPERTY OF THE FIRST:
-# the root directory the worktrees sit in, and the prefix their directory names
-# carry. `plot-wt-` exists to make Plot's worktrees identifiable AMONG UNRELATED
-# directories — it is a workaround for sharing a parent with other projects.
-# Under a dedicated `Worktree root:` the directory already says what they are,
-# so the prefix answers a question nobody is asking and is dropped. The legacy
-# default keeps it, where it is still doing its job. Two conventions coexist
-# permanently, and that is the intended outcome, not a transition cost.
-#
-#   `Worktree root:` absent  → repo_root/.. , prefix `plot-wt-`   (today's behaviour)
-#   relative value           → repo_root/<value> , NO prefix
-#   absolute value           → <value> as given , NO prefix
+# Two facts: the root directory the worktrees sit in, and the prefix their
+# directory names carry. The root is the desk root, `deskRoot`'s answer asked
+# through `plot-desk-root.sh`:
+#
+#   `Worktree root:` absent or empty → <main checkout>/.worktrees
+#   relative value                   → <main checkout>/<value>
+#   absolute value                   → <value> as given
+#
+# The prefix is always empty. `plot-wt-` made Plot's worktrees identifiable
+# among unrelated directories in the checkout's parent; the desk root is a
+# directory Plot owns, so the directory already says what they are. Desks a
+# dispatch created under the old default keep their `plot-wt-` names and their
+# place: every read of "which worktree holds this branch" asks `git worktree
+# list`, and `plot-reap.sh` still recognises the legacy path.
+#
+# The root is the MAIN checkout's, wherever this runs: inside a desk,
+# `--show-toplevel` answers the desk and `.worktrees` would resolve beneath it.
+# There is NO FALLBACK: when the rule cannot be asked, dispatch stops with the
+# reason rather than compute a second default.
 #
 # THIS FUNCTION ONLY COMPOSES A ROOT AND A PREFIX. It is the CREATION side. Every
 # read of "which worktree holds this branch" asks `git worktree list` instead —
 # see THE HELD-BRANCH GATE. A second naming convention gives path-guessing a
 # second way to be wrong, so path-guessing is confined to creation alone.
-resolve_wt_root() { # $1=repo_root → sets globals wt_root, wt_prefix
-  local rr="$1" configured
-  configured=$("$script_dir/plot-config.sh" get "Worktree root" "")
-  if [ -z "$configured" ]; then
-    # The legacy default: beside the repo, prefixed. No existing checkout moves.
-    wt_root=$(cd "$rr/.." && pwd)
-    wt_prefix="plot-wt-"
-    return
-  fi
-  case "$configured" in
-    /*) wt_root="$configured" ;;                 # absolute: taken as given
-    *)  wt_root="$rr/$configured" ;;             # relative: against the repo root
-  esac
-  # Normalise away a trailing slash so composed paths never double it. The
-  # directory may not exist yet (created on first dispatch), so this is pure
-  # string work, not a `cd`.
-  wt_root="${wt_root%/}"
+# shellcheck source=plot-desk-root.sh
+. "$script_dir/plot-desk-root.sh"
+resolve_wt_root() { # sets globals wt_root, wt_prefix; exits 3 when unaskable
+  wt_root=$(plot_desk_root "$(plot_repo_root)") || {
+    echo "plot-dispatch: cannot resolve where the worktrees go — nothing was dispatched." >&2
+    exit 3
+  }
   wt_prefix=""
 }
 
@@ -1645,9 +1642,13 @@ charter_file_for() { # $1 = agent name → prints the path it would read
 # inspectable and stoppable even if the plan was since delivered or rejected.
 # Refusing to show a running worker because of a phase change would strand it.
 repo_root_early=$(git rev-parse --show-toplevel)
-resolve_wt_root "$repo_root_early"
-wt_root_early="$wt_root"
-wt_prefix_early="$wt_prefix"
+# Only the two verbs that enumerate desks ask for the root here; every other
+# path asks where it composes one, so its own refusals answer first.
+if [ "$mode" = status ] || [ "$mode" = stop ]; then
+  resolve_wt_root
+  wt_root_early="$wt_root"
+  wt_prefix_early="$wt_prefix"
+fi
 
 # States: "running <pid>" | "finished <pid>" | "waiting <pid> (answer it)"
 #       | "stalled <pid> (work unfinished)" | "failed <pid> (exit N)"
@@ -2160,7 +2161,6 @@ if [ "$mode" = "start" ]; then
   # about any plan, so there is no plan whose phase could refuse it. A gate on a
   # slug this verb never takes would refuse every call.
   repo_root="$repo_root_early"
-  resolve_wt_root "$repo_root"
 
   # THE DEFAULT BRANCH, by the same three steps the fan-out takes below — the
   # config key, then origin's own HEAD, then `main`. Resolved here because the
@@ -2370,6 +2370,9 @@ EOF
   # `wait_for_work` skips the outlook scan for an agent that holds none.
   slug=""
 
+  # Where the desks go, asked only now: every refusal above answers first, and
+  # a broken runtime is named by the start-command check rather than here.
+  resolve_wt_root
   start_made=0
   start_i=0
   while [ "$start_i" -lt "$start_n" ]; do
@@ -2423,6 +2426,9 @@ EOF
       continue
     fi
     mkdir -p "$wt_root" 2>/dev/null || true
+    # The desk root lies inside the repository by default, so keep it out of
+    # `git status` the moment it exists.
+    plot_exclude_desk_root "$(plot_repo_root)"
     if ! git worktree add -q --detach "$start_wt" "origin/$start_main" 2>/dev/null; then
       # NO REMOTE REF IS NOT A FAILURE OF THIS VERB. A fresh clone or a repo
       # with no remote has no `origin/<main>`; the local one is the same commit
@@ -2438,10 +2444,7 @@ EOF
     # the marker is ignored via `info/exclude` rather than `.gitignore`, because
     # an untracked file in a desk reads as unlanded work to
     # `plot-worker-state.sh` and would make every free agent look stalled.
-    _excl="$(git -C "$start_wt" rev-parse --git-common-dir 2>/dev/null)/info/exclude"
-    if [ -f "$_excl" ] && ! grep -qxF '.metadata_never_index' "$_excl" 2>/dev/null; then
-      printf '%s\n' '.metadata_never_index' >> "$_excl" 2>/dev/null || true
-    fi
+    plot_desk_exclude "$start_wt" '.metadata_never_index'
     : > "$start_wt/.metadata_never_index" 2>/dev/null || true
 
     echo "  desk $start_wt (detached at origin/$start_main)"
@@ -2484,8 +2487,9 @@ if [ "$mode" = "migrate" ]; then
   configured_root=$("$script_dir/plot-config.sh" get "Worktree root" "")
   if [ -z "$configured_root" ]; then
     echo "plot-dispatch --migrate: no 'Worktree root:' configured — nothing to migrate."
-    echo "  When Worktree root is absent, worktrees live beside the repo (plot-wt-*)."
-    echo "  To migrate, first add a 'Worktree root:' key to ## Plot Config."
+    echo "  When Worktree root is absent, new worktrees go to <repo>/.worktrees;"
+    echo "  desks an older dispatch made beside the repo (plot-wt-*) stay there."
+    echo "  To move those, first add a 'Worktree root:' key to ## Plot Config."
     exit 0
   fi
 
@@ -3042,13 +3046,12 @@ run_waits_preflight() { # → prints refusals; fills waits_held, adds to n_skipp
 }
 
 # Where the worktrees live and what their names carry — see resolve_wt_root.
-# The default is beside the repo with the `plot-wt-` prefix; a `Worktree root:`
-# key relocates them (and drops the prefix, which was only earning its keep
-# among unrelated sibling directories). A nested root is made invisible to
-# `git status` and the marker grep by a `.gitignore` line, not by living
-# outside the repo.
+# The default is `<main checkout>/.worktrees` with no prefix; a `Worktree root:`
+# key relocates them. A root inside the repository is kept out of `git status`
+# by the `info/exclude` line `plot_exclude_desk_root` writes when a desk is
+# created.
 repo_root=$(git rev-parse --show-toplevel)
-resolve_wt_root "$repo_root"
+resolve_wt_root
 
 n_dispatched=0 n_reused=0 n_skipped=0 n_started=0
 n_brief_asked=0
@@ -3289,6 +3292,9 @@ write_started_record() { # $@ = branches
   # stale tip and the push would be a guaranteed non-fast-forward.
   git fetch -q origin "$MAIN" 2>/dev/null
 
+  # `git worktree add` creates the desk root when it is missing; exclude it
+  # first so the booking leaves no untracked `.worktrees/` behind.
+  plot_exclude_desk_root "$(plot_repo_root)"
   # -B: a leftover branch from an earlier failed booking must not block this
   # one. It is disposable by construction — created here, pushed, deleted.
   if ! git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null; then

package/plot-host.sh

@@ -247,7 +247,9 @@
 #                                 list` (no --json), pinned to bb 0.6.0. EXIT 4
 #                                 narrows rather than disappears: it is the
 #                                 tracker-DISABLED case (bb answers 404/410),
-#                                 which stays *this host cannot answer* where an
+#                                 and a bb whose `--help` lists no `issue`
+#                                 command (Quatico bb), both of
+#                                 which stay *this host cannot answer* where an
 #                                 empty list would say *there are none*. A call
 #                                 that failed on an enabled tracker, or any error
 #                                 wording this adapter does not recognise, exits
@@ -281,7 +283,8 @@
 #                                 Same three outcomes as issue-list, same codes:
 #                                 BITBUCKET NOW ANSWERS via `bb issue view`
 #                                 (pinned to 0.6.0); `url` comes from the view's
-#                                 footer. EXIT 4 is the tracker-DISABLED case,
+#                                 footer. EXIT 4 is the tracker-DISABLED case
+#                                 or a bb with no `issue` command,
 #                                 EXIT 3 a lookup that failed or an unrecognised
 #                                 error. An issue that does not exist is a
 #                                 FAILURE here, not an empty body: the caller
@@ -1016,7 +1019,7 @@ bb_state_listing() { # global bb args… --state <s> --json → one JSON array
     esac
   done
   [ -n "$_st" ] || die "bb_state_listing: no --state"
-  _out="$(bb ${_args[@]+"${_args[@]}"} api "/repositories/{ws}/{repo}/pullrequests?state=$(bb_query_state "$_st")&pagelen=50")" || return $?
+  _out="$(bb ${_args[@]+"${_args[@]}"} api "/repositories/{ws}/{repo}/pullrequests?state=$(bb_query_state "$_st")&pagelen=$BB_LIST_PAGELEN")" || return $?
   printf '%s' "$_out" | jq -c '.values // []'
 }
 
@@ -2033,17 +2036,41 @@ bb_issue_exit_code() {
 # fails LOUDLY rather than silently mis-reading a column that may have moved.
 # `PLOT_BB_SKIP_VERSION_CHECK` exists for the test harness, whose stub bb has no
 # meaningful version — the parse is exercised against captured fixture text.
+#
+# A VERSION MISMATCH IS NOT ALWAYS A MOVED FORMAT. Two products share the name
+# `bb` (see the capability check below), and Quatico `bb` — 1.9.0 measured
+# 2026-10-01 — has no `issue` command at all: `bb --help` lists `pr …`,
+# `source …` and `api`. Telling it to update would suggest a fix that does not
+# exist, so a mismatch first asks `bb --help` what the CLI offers. A help text
+# that lists a `pr` command and no `issue` command is a bb that cannot be asked
+# about issues, which is exit 4 — the same answer as a disabled tracker. Any
+# other help text keeps the refusal below, exit 3. Exits 4 or 3; 0 passes.
 bb_assert_issue_version() {
   [ -n "${PLOT_BB_SKIP_VERSION_CHECK:-}" ] && return 0
   local v
   v="$(bb --version 2>/dev/null | bb_strip_ansi | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)"
   if [ "$v" != "$BB_ISSUE_VERSION" ]; then
+    if bb_lacks_issue_command; then
+      echo "plot-host: bb ${v:-unknown} lists no issue command — Quatico bb has none, unlike craftamap/bb — so this repository's issues cannot be read through it; declare the issue tracker with the \`Tracker\` config key" >&2
+      return 4
+    fi
     echo "plot-host: bb issue parse targets $BB_ISSUE_VERSION but found '${v:-unknown}' — refusing to mis-read a format that may have moved" >&2
     return 3
   fi
   return 0
 }
 
+# Whether `bb --help` lists commands and `issue` is not one of them. A help
+# that lists no `pr` command either is not a command listing this can read, so
+# it answers *not proven* (1) and the caller keeps its exit-3 refusal: guessing
+# 4 from unreadable help would turn a broken bb into *no issue tracker*.
+bb_lacks_issue_command() {
+  local help
+  help="$(bb --help 2>&1 | bb_strip_ansi)" || return 1
+  grep -qE '^[[:space:]]+pr([[:space:]]|$)' <<<"$help" || return 1
+  ! grep -qE '^[[:space:]]+issues?([[:space:]]|$)' <<<"$help"
+}
+
 # --- bb capability check (--json support) ------------------------------------
 #
 # TWO TOOLS SHARE THE NAME `bb`. craftamap/bb is a Go binary that does NOT
@@ -2516,27 +2543,36 @@ jira_check() {
 # `bb` returned 50 merged PRs (ids 836→787) against a repo numbering to 836, so
 # ~780 older merged PRs were invisible to the join.
 #
-# THE DETECTOR IS AGAINST THE REQUESTED LIMIT, NEVER THE CONSTANT 50. A future
-# `bb` page size of 100 must not make a truncated 100-row list report complete —
-# this plan's own defect restored. So the rule names no page size:
+# THE RULE IS `rules/listing-page.ts`'s `pagePossiblyTruncated`, and this is
+# its shell copy. `pr-list` runs on every board refresh, so the shell keeps the
+# rule rather than asking a bundle (docs/shell-and-domain.md), and
+# `packages/domain/corpus/listing-page.corpus.test.ts` holds the pair:
 #
 #   github (HONOURS --limit)  : a state is possibly truncated when it returned
-#                               AT LEAST the requested limit — the host may have
-#                               had more that the limit hid. Fewer rows than the
-#                               limit PROVES completeness.
-#   bitbucket (IGNORES --limit): `bb pr list` has no --limit and reports neither
-#                               a total nor a cursor, so it can NEVER prove
-#                               completeness for a --limit call. Any non-empty
-#                               page is therefore possibly truncated. An empty
-#                               page had nothing to truncate.
-#
-# THE PREMISE ABOVE IS ABOUT `bb pr list`, AND IT WAS ONCE WRITTEN ABOUT
-# BITBUCKET. It said the host "cannot report a total or a cursor" — true of the
-# CLI's listing and false of the REST endpoint behind it, which carries both a
-# `size` and a `next`. That mattered the moment a path existed that could ask:
-# the per-branch sweep (#333) proves completeness exactly, per branch, and this
-# detector is deliberately not asked about it (`pr_list_states`). The rule below
-# is unchanged and still governs every listing call.
+#                               AT LEAST the requested limit. Fewer rows than
+#                               the limit PROVES completeness.
+#   bitbucket (ONE FIXED PAGE): the listing ignores --limit and returns one page
+#                               per state. A page SHORTER than the page length
+#                               is the last page, so it is complete. A page AT
+#                               the length stays possibly truncated.
+#
+# THE PAGE LENGTH IS A READING, NEVER A CONSTANT THE RULE NAMES. The listing
+# asks `pagelen=$BB_LIST_PAGELEN` through `bb api`, and the length holds only
+# where that `bb` passes the query through unchanged, so it is read per version
+# from `BB_LIST_PAGE_VERSIONS` — pinned like `BB_ISSUE_VERSION`. A version
+# nobody measured has no length, and every non-empty page under it stays
+# possibly truncated: the rule never calls a page complete it cannot prove. A
+# future length of 100 is a new table entry, never a page of 50 read as short.
+#
+# Measured on `quatico/quaweb-website`: bb 1.9.0 returned 50 merged rows in one
+# request on 2026-09-30, and on 2026-10-01 answered `pagelen: 50` with 50 rows,
+# a `next` and `size: 895`. Before
+# 2026-10-01 every non-empty Bitbucket page was reported, so 20 open PRs read as
+# truncated on every refresh (#1137).
+#
+# THE PER-BRANCH SWEEP AND THE WINDOWED LISTING MAKE NO PAGE CLAIM. The sweep
+# proves completeness per branch and the window refuses a short read, so this
+# detector is not asked about either (`pr_list_states`).
 #
 # No --limit was requested → the caller accepted the host's default page and is
 # owed no report, so no existing no-limit caller's behaviour changes.
@@ -2555,18 +2591,40 @@ jira_check() {
 # future diff that teaches the scan to fall back, without moving the failure
 # into a minutes-long pulse. See the plan's Done-when item 3.
 #
+# The page length Bitbucket's plain listing asks for. `bb_state_listing` sends
+# it, and `pr_list_report_truncation` reads it as the page length only for a
+# `bb` in BB_LIST_PAGE_VERSIONS.
+BB_LIST_PAGELEN=50
+
+# The `bb` versions measured to pass `pagelen` through `bb api` unchanged,
+# space-separated. `adapters/host/listing-paging.ts` holds the same table.
+BB_LIST_PAGE_VERSIONS="1.9.0"
+
+# The page length the answering `bb` lists by, or nothing where its version is
+# not in BB_LIST_PAGE_VERSIONS. Reads the version `bb_require_json` recorded,
+# so it costs no `bb` call; a skipped capability check records no version.
+bb_list_page_length() {
+  local v="${BB_CAP_IDENTITY#*/}"
+  case " $BB_LIST_PAGE_VERSIONS " in
+    *" $v "*) printf '%s\n' "$BB_LIST_PAGELEN" ;;
+  esac
+}
+
 # $1 backend  $2 requested limit (may be "")  $3 state word  $4 row count
 pr_list_report_truncation() {
-  local be="$1" limit="$2" state="$3" count="$4"
+  local be="$1" limit="$2" state="$3" count="$4" len=""
   [ -n "$limit" ] || return 0            # no --limit → no completeness claim owed
   [ "$count" -gt 0 ] 2>/dev/null || return 0   # an empty page had nothing to hide
   if [ "$be" = "github" ]; then
     # github honours the limit: complete unless the page came back AT the limit.
     [ "$count" -ge "$limit" ] 2>/dev/null || return 0
+  else
+    # A fixed page: complete below a measured page length, unprovable otherwise.
+    [ "$be" = "bitbucket" ] && len="$(bb_list_page_length)"
+    if [ -n "$len" ] && [ "$count" -lt "$len" ] 2>/dev/null; then return 0; fi
   fi
-  # bitbucket: any non-empty page for a --limit call is unprovable, so it falls
-  # through to the report. Named per state so a future caller can resolve exactly
-  # the states that were capped, not a whole-call flag that over-reports.
+  # Named per state so a caller can resolve exactly the states that were
+  # capped, not a whole-call flag that over-reports.
   echo "plot-host: $be pr-list state=$state possibly truncated ($count rows, requested limit $limit unprovable) — a join against this page may read older branches as 'no PR' (#333)" >&2
 }