@plot-pm/board 0.14.3 → 0.14.4

package/package.json

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

@@ -61,6 +61,30 @@
 #   pr-ready <number>              take a PR out of draft
 #                                 merge the PR
 #   pr-list [--state open|merged|closed|all] [--limit N] [--rich]
+#                                 [--since <iso>] narrows the listing to pull
+#                                 requests the host has seen change since that
+#                                 stamp. Measured 2026-09-21 on this repository:
+#                                 one `--state all` over 933 pull requests takes
+#                                 29 811 ms with the fields the board needs, and
+#                                 the same call over one day takes 943 ms for 3
+#                                 rows — factor 32, with every expensive field
+#                                 still included.
+#                                 THE STAMP IS THE HOST'S OWN, passed through
+#                                 byte-for-byte: a caller that re-renders it
+#                                 sends its own clock's spelling, and a client
+#                                 two seconds fast excludes the PRs updated in
+#                                 that gap from every later window — forever,
+#                                 because the window never reopens.
+#                                 GITHUB NARROWS AND BITBUCKET'S BULK LISTING
+#                                 CANNOT. `gh pr list` takes `--search`; `bb pr
+#                                 list` has no query flag at all (verified
+#                                 against bb 1.9.0: `unknown flag: --query`), so
+#                                 only the per-branch sweep's REST `q=` can
+#                                 carry it. The bulk Bitbucket listing SAYS it
+#                                 could not narrow and answers in full, because
+#                                 a full answer reported as a delta is what
+#                                 would let a caller advance a watermark over a
+#                                 window it never applied.
 #                                 [--repo <owner/repo>] pins the list to ONE
 #                                 repository, exactly as pr-state and pr-merged
 #                                 do. A checkout with remotes on two hosts lets
@@ -70,7 +94,24 @@
 #                                 JSON lines: {"number":N,"title":"...",
 #                                 "state":"...","head":"..."}
 #                                 --rich adds: draft, checks, mergeable, review,
-#                                 url, failing_checks — `failing_checks` names
+#                                 url, updatedAt, failing_checks —
+#                                 `updatedAt` is WHEN THE HOST LAST SAW THE PR
+#                                 CHANGE, in the host's own words and on the
+#                                 host's own clock (`updatedAt` on GitHub,
+#                                 `updated_on` on Bitbucket), "" where the CLI
+#                                 omits it. It is the field a durable store
+#                                 advances its watermark by, and it is the
+#                                 host's rather than this machine's because a
+#                                 client clock two seconds fast would exclude
+#                                 every PR updated in that gap from every later
+#                                 window — permanently, and silently.
+#                                 Measured 2026-09-21: over 937 PRs,
+#                                 `number,updatedAt` is 4715 ms against 5417 ms
+#                                 for the base fields and 18842 ms for
+#                                 `statusCheckRollup`. Asked on --rich ONLY —
+#                                 the plain arm is the cheap one and no shell
+#                                 caller reads a watermark.
+#                                 `failing_checks` names
 #                                 WHICH checks failed, the detail `checks`
 #                                 collapses to one word, from the same response
 #                                 at no extra call; [] on bitbucket and wherever
@@ -718,6 +759,24 @@ bb_branch_query() { # $1=branch $2=adapter state; rest=global bb args → values
   local _br="$1" _st="$2"; shift 2
   local _q _path _out _rc
   _q="state=$(url_encode "\"$(bb_query_state "$_st")\"") AND source.branch.name=$(url_encode "\"$_br\"")"
+  # THE WINDOW COMPOSES WITH THE STATE FILTER AND NEVER REPLACES IT. Bitbucket
+  # takes ONE `q=` parameter, so a second one would silently win or lose
+  # depending on the host's parsing — and either way the state clause this query
+  # is built around would be the term at risk. `AND` is the same conjunction the
+  # two terms above already use.
+  #
+  # ENCODED LIKE EVERY OTHER TERM ON THIS PATH, and an ISO stamp needs it: `:`
+  # and `-` are not in `url_encode`'s safe set, and the block header records
+  # what an unencoded value costs — `/` ends the filter early, so the query asks
+  # about one thing and answers about another.
+  #
+  # `>=` RATHER THAN `>`, and the asymmetry with the GitHub arm is deliberate.
+  # Bitbucket's `updated_on` carries microseconds and GitHub's stamp does not,
+  # so an exclusive comparison against a truncated stamp would drop a PR updated
+  # inside the same second. Re-reading one row the caller already holds costs a
+  # row; missing one costs a change nobody ever sees again.
+  [ -n "$PR_LIST_SINCE" ] \
+    && _q="$_q AND updated_on>=$(url_encode "\"$PR_LIST_SINCE\"")"
   # The space between the two terms is encoded too; `bb api` passes the path to
   # curl verbatim and an unencoded space would truncate the request line.
   _q="${_q// /%20}"
@@ -824,6 +883,19 @@ bb_branch_sweep() { # global bb args… --state <s> --json → one JSON array
 # separator is git's guarantee rather than a hopeful convention.
 PR_LIST_BRANCHES=""
 
+# The window a sweep's query carries, the host's own stamp. Empty means ask
+# about everything, which is what every caller predating `--since` asks.
+#
+# A GLOBAL FOR `PR_LIST_BRANCHES`' REASON, and it travels the same route: the
+# `pr-list` arm sets it immediately before the call, `bb_branch_sweep` passes
+# through without reading it, and `bb_branch_query` composes it into the one
+# `q=` Bitbucket takes. Threading it through the sweep as an argument would mean
+# teaching that function a parameter it only forwards, and its header already
+# refuses the mirror of that — "teaching `pr_list_states` which of its commands
+# is a sweep would put a backend's shape inside the one piece of this file that
+# has none."
+PR_LIST_SINCE=""
+
 # How many branches the last sweep asked about, and how many answered.
 #
 # THE COMPLETENESS SIGNAL, AND WHY THE ARM STATES IT RATHER THAN THE SCAN
@@ -2469,6 +2541,18 @@ backend() {
 # written beside it.
 . "$here/plot-budget.sh"
 
+# THE MEMO IS SWEPT ON THE WAY OUT. `budget_rate` caches its reading under
+# `$PLOT_BUDGET_HOME/memo/$$` because a command substitution is a subshell and a
+# variable set inside one does not survive it — see the block above
+# `budget_rate`. A directory keyed on a pid must be removed by the process that
+# made it, or a long-lived machine accumulates one per `plot-host.sh` call.
+#
+# `EXIT` ALONE, deliberately. It runs on a normal return and on an uncaught
+# signal's default termination path is irrelevant here: the sweep is an
+# optimisation's housekeeping, and a cache that outlives one run costs a stale
+# reading at worst, which is the same staleness the memo grants by design.
+trap 'budget_memo_clear' EXIT
+
 # WHO IS SPENDING — read from the CLI's own config, never from an API call.
 #
 # `gh api user` would answer authoritatively and cost one request against the
@@ -3302,12 +3386,22 @@ case "$op" in
     # existing caller's result changes.
     limit=""
     branches=""
+    # THE WINDOW, AND IT IS THE HOST'S OWN STAMP. Empty means ask about
+    # everything, which is what every caller predating this asks and what a
+    # caller with no stored watermark must ask. A caller that has one sends it
+    # verbatim — see the header: re-rendering it is how a window closes forever.
+    since=""
     while [ $# -gt 0 ]; do
       case "$1" in
         --state) state="${2:?}"; shift 2 ;;
         --limit) limit="${2:?}"; shift 2 ;;
         --rich) rich=1; shift ;;
         --repo) repo_args=(-R "${2:?}"); shift 2 ;;
+        # `${2:?}` REFUSES AN EMPTY VALUE, and that is the point rather than
+        # boilerplate. `--since ""` would reach GitHub as `--search "updated:>"`,
+        # a syntax error the host may answer with everything or with nothing —
+        # and a caller whose watermark was null would send exactly that.
+        --since) since="${2:?}"; shift 2 ;;
         # THE BRANCHES THE CALLER TRACKS, repeatable, and OPT-IN. Given any,
         # the Bitbucket arm sweeps the REST endpoint once per branch per state
         # instead of listing the repository; given none, every existing caller
@@ -3328,6 +3422,23 @@ case "$op" in
     done
     limit_args=()
     [ -n "$limit" ] && limit_args=(--limit "$limit")
+    # THE WINDOW AS GITHUB TAKES IT, built once and appended at all three call
+    # sites — the same argument `pr_list_call`'s header makes about the six
+    # hand-applied fixes: three sites each composing their own search string is
+    # three places for the next window's shape to drift.
+    #
+    # `updated:>` is EXCLUSIVE, and that is the safe direction here. The
+    # watermark is the stamp of a row the caller has ALREADY stored, so
+    # excluding it re-asks nothing; including it would re-fetch that row every
+    # pass for no new information. A PR updated in the same second as the
+    # watermark is the one this can miss, and the periodic full read the caller
+    # is required to keep making is what corrects it.
+    #
+    # THE STAMP IS NOT QUOTED INSIDE THE QUERY. `gh` sends `--search`'s value as
+    # one API parameter and an ISO-8601 stamp carries no space, so a quote would
+    # travel to GitHub as part of the term and match nothing.
+    search_args=()
+    [ -n "$since" ] && search_args=(--search "updated:>$since")
 
     # --- Jenkins CI integration (orthogonal to Git host) ---
     # When `CI: jenkins` is configured, build status comes from Jenkins rather
@@ -3438,8 +3549,8 @@ case "$op" in
           #   $jstatus != "ok"  → Jenkins could not answer; every row `unknown`.
           #   $jentry == null   → the branch has no Jenkins job; `none`.
           #   otherwise         → the joined colour's `checks`, job named on fail.
-          _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
-            --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url)" || exit $?
+          _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
+            --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url,updatedAt)" || exit $?
           pr_list_report_truncation github "$limit" "$state" \
             "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
           printf '%s' "$_gh_raw" \
@@ -3459,6 +3570,7 @@ case "$op" in
                   else "unknown" end),
                 review:(.reviewDecision // ""),
                 url:.url,
+                updatedAt:(.updatedAt // ""),
                 failing_checks:(
                   if $jentry != null and $jentry.checks == "failing"
                   then [$jentry.job]
@@ -3467,8 +3579,8 @@ case "$op" in
               }'
         else
           # GitHub without Jenkins (or Jenkins not configured): use GitHub rollup
-          _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
-            --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url)" || exit $?
+          _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
+            --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url,updatedAt)" || exit $?
           pr_list_report_truncation github "$limit" "$state" \
             "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
           printf '%s' "$_gh_raw" \
@@ -3490,6 +3602,7 @@ case "$op" in
                   else "unknown" end),
                 review:(.reviewDecision // ""),
                 url:.url,
+                updatedAt:(.updatedAt // ""),
                 failing_checks:[
                   .statusCheckRollup[]? | select((if (.conclusion // "") != "" then .conclusion else (.status // .state) end) as $c
                     | $c=="FAILURE" or $c=="ERROR" or $c=="CANCELLED"
@@ -3498,7 +3611,7 @@ case "$op" in
               }'
         fi
       else
-        _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} \
+        _gh_raw="$(pr_list_call gh ${repo_args[@]+"${repo_args[@]}"} pr list --state "$state" ${limit_args[@]+"${limit_args[@]}"} ${search_args[@]+"${search_args[@]}"} \
           --json number,title,state,headRefName)" || exit $?
         pr_list_report_truncation github "$limit" "$state" \
           "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
@@ -3543,6 +3656,23 @@ case "$op" in
       # ways, which is how the six hand-applied fixes `pr_list_call` warns about
       # began. One assignment here; the sites are untouched but for this word.
       PR_LIST_BRANCHES="$branches"
+      # THE WINDOW REACHES THE SWEEP AND NOT THE LISTING, and the asymmetry is
+      # the CLI's rather than a choice. `bb pr list` takes `--state`, `--author`,
+      # `--json` and `--jq` and no query flag at all — verified against bb 1.9.0,
+      # which answers `unknown flag: --query` — so the only Bitbucket path that
+      # can carry `updated_on` is `bb_branch_query`'s own REST `q=`.
+      #
+      # SAID RATHER THAN SWALLOWED, for the reason `--limit` two blocks up is
+      # said: a caller that asked for a window and got a full listing must not
+      # read the answer as a delta. It would advance its watermark over a window
+      # it never applied — harmless this pass, since a full listing holds every
+      # row a narrow one would, and wrong the moment the caller uses the flag to
+      # decide whether its answer was complete.
+      PR_LIST_SINCE="$since"
+      if [ -n "$since" ] && [ -z "$branches" ]; then
+        echo "plot-host: bitbucket ignores --since $since on a listing; bb pr list has no query flag (bb 1.9.0) — answering in full" >&2
+        PR_LIST_SINCE=""
+      fi
       PR_SWEEP_ASKED=0
       bb_cmd=(bb ${repo_args[@]+"${repo_args[@]}"} pr list)
       if [ -n "$branches" ]; then
@@ -3574,6 +3704,7 @@ case "$op" in
                   mergeable:"unknown",
                   review:"",
                   url:(.links.html.href // ""),
+                  updatedAt:(.updated_on // ""),
                   failing_checks:(
                     if $jentry != null and $jentry.checks == "failing"
                     then [$jentry.job]
@@ -3584,7 +3715,7 @@ case "$op" in
           # Bitbucket without Jenkins: checks remain unknown
           PR_LIST_JQ_ARGS=()
           pr_list_states bitbucket "$limit" "$bb_states" \
-            '.[] | {number:.id,title:.title,state:(if .state=="DECLINED" then "CLOSED" else .state end),head:.source.branch.name,draft:(.draft // false),checks:"unknown",mergeable:"unknown",review:"",url:(.links.html.href // ""),failing_checks:[]}' \
+            '.[] | {number:.id,title:.title,state:(if .state=="DECLINED" then "CLOSED" else .state end),head:.source.branch.name,draft:(.draft // false),checks:"unknown",mergeable:"unknown",review:"",url:(.links.html.href // ""),updatedAt:(.updated_on // ""),failing_checks:[]}' \
             "${bb_cmd[@]}" || exit $?
         fi
       else

package/plot-reap.sh

@@ -385,11 +385,19 @@ manifest_for() {
 reap=0; kept=0; removed=0; cleared=0; vanished=0; unplaced=0
 printf '%-8s %-52s %s\n' "verdict" "branch" "why"
 
-while IFS=$'\t' read -r wt br prunable; do
+while IFS=$'\037' read -r wt br prunable; do
   [ -n "$wt" ] || continue
   short=${br#refs/heads/}
   [ "$wt" = "$ROOT" ] && continue
 
+  # WHAT THE REPORT CALLS THIS TREE. `short` is the branch and stays empty for
+  # a detached desk, which is the correct reading and a useless label — an
+  # operator reading a blank column cannot tell which of thirteen it names.
+  # The directory is what identifies such a tree, so the report says so and
+  # every refusal still measures `short`.
+  label=$short
+  [ -z "$label" ] && label="(detached) $(basename "$wt")"
+
   # 4a. GIT'S OWN ANSWER THAT THE DIRECTORY IS GONE, and it is a REPORT rather
   #     than a sixth refusal. The five below each say *do not remove this* and
   #     send an operator to look; this says *there is nothing to remove and the
@@ -414,7 +422,7 @@ while IFS=$'\t' read -r wt br prunable; do
   #     prune stays the operator's decision — the same discipline that makes
   #     every refusal a measurement rather than an act.
   if [ "$prunable" = "yes" ]; then
-    printf '%-8s %-52s %s\n' "vanished" "$short" "directory gone — 'git worktree prune' clears the entry"
+    printf '%-8s %-52s %s\n' "vanished" "$label" "directory gone — 'git worktree prune' clears the entry"
     vanished=$((vanished+1)); continue
   fi
 
@@ -482,7 +490,7 @@ while IFS=$'\t' read -r wt br prunable; do
   # population the rule excludes. It counts, because a refusal that counts is
   # the difference between *nothing to clean* and *nothing was looked at*.
   if [ "$unclassified" = true ]; then
-    printf '%-8s %-52s %s\n' "unknown" "$short" \
+    printf '%-8s %-52s %s\n' "unknown" "$label" \
       "under $(basename "$WT_ROOT")/, no worker pid and no recognised name — needs a person"
     unplaced=$((unplaced+1)); continue
   fi
@@ -531,6 +539,25 @@ while IFS=$'\t' read -r wt br prunable; do
     merge=merged; why="merged into $DEFAULT"
   elif [ -n "$short" ] && pr_merged "$short"; then
     merge=merged; why="PR merged (squash)"
+  elif [ -z "$short" ] \
+       && [ "$(git -C "$wt" rev-list --count "origin/$DEFAULT..HEAD" 2>/dev/null || echo 1)" = "0" ]; then
+    # A DETACHED DESK HAS NOTHING TO LAND, and that is a measurement rather
+    # than a weakened refusal. `plot-dispatch.sh --start` cuts a free agent's
+    # desk detached at `origin/<main>` because a free agent holds no slice, so
+    # such a tree never had a branch and can never have a PR. Reading it
+    # through `no-merged-pr` would refuse every one of them forever — the same
+    # silence this slice removes, in the opposite direction.
+    #
+    # THE READING IS `HEAD` AGAINST THE DEFAULT BRANCH, never the desk's name.
+    # Measured 2026-09-22: three `free-*` desks hold a branch and two carry
+    # live workers (pids 27820, 6542), so a prefix-keyed test reaps a running
+    # agent. Detachment is the condition; the name is not.
+    #
+    # A detached desk carrying commits falls through to `not-merged` and is
+    # kept, which is correct: somebody committed there and nothing says the
+    # work landed. The live-pid, marker and dirty refusals are all asked
+    # before this and are unaffected.
+    merge=merged; why="detached, nothing to land"
   fi
 
   # THE DECISION. One call, and the script holds no `if` about whether a
@@ -599,11 +626,11 @@ NODE_EOF
       no-merged-pr)        reason="unlanded work — no merged PR" ;;
       *)                   reason="rule could not be asked — keeping" ;;
     esac
-    printf '%-8s %-52s %s\n' "keep" "$short" "$reason"; kept=$((kept+1)); continue
+    printf '%-8s %-52s %s\n' "keep" "$label" "$reason"; kept=$((kept+1)); continue
   fi
 
   if [ "$MAX" -gt 0 ] && [ "$reap" -ge "$MAX" ]; then
-    printf '%-8s %-52s %s\n' "keep" "$short" "--max $MAX reached"; kept=$((kept+1)); continue
+    printf '%-8s %-52s %s\n' "keep" "$label" "--max $MAX reached"; kept=$((kept+1)); continue
   fi
 
   # Resolved BEFORE the removal, because `canonical` needs the directory to
@@ -619,7 +646,7 @@ NODE_EOF
 
   reap=$((reap+1))
   if [ "$DRY" -eq 1 ]; then
-    printf '%-8s %-52s %s\n' "would" "$short" "$why${logs:+, log $logs}"
+    printf '%-8s %-52s %s\n' "would" "$label" "$why${logs:+, log $logs}"
   else
     if git worktree remove --force "$wt" 2>/dev/null; then
       # The worktree is gone; NOW the manifest may go. Inside the success arm
@@ -647,16 +674,16 @@ NODE_EOF
         while IFS= read -r f; do rm -f "$f" 2>/dev/null; done < <(branch_log_files "$short")
         why="$why, log removed"
       fi
-      printf '%-8s %-52s %s\n' "reaped" "$short" "$why"; removed=$((removed+1))
+      printf '%-8s %-52s %s\n' "reaped" "$label" "$why"; removed=$((removed+1))
     else
-      printf '%-8s %-52s %s\n' "FAILED" "$short" "git worktree remove refused"; kept=$((kept+1))
+      printf '%-8s %-52s %s\n' "FAILED" "$label" "git worktree remove refused"; kept=$((kept+1))
     fi
   fi
 done < <(git worktree list --porcelain \
-          | awk '/^worktree /{ if (br != "") print p"\t"br"\t"pr; p=$2; br=""; pr="no"; next }
+          | awk -v OFS="\037" '/^worktree /{ if (p != "") print p, br, pr; p=$2; br=""; pr="no"; next }
                  /^branch /  { br=$2; next }
                  /^prunable/ { pr="yes"; next }
-                 END         { if (br != "") print p"\t"br"\t"pr }')
+                 END         { if (p != "") print p, br, pr }')
 
 [ "$DRY" -eq 0 ] && git worktree prune 2>/dev/null