@plot-pm/board 0.16.2 → 0.16.3

package/plot-host.sh

@@ -71,7 +71,54 @@
 #   pr-merge <number> [--squash] [--delete-branch]
 #   pr-ready <number>              take a PR out of draft
 #                                 merge the PR
-#   pr-list [--state open|merged|closed|all] [--limit N] [--rich]
+#   pr-list [--state open|merged|closed|all] [--limit N] [--rich|--rich-open]
+#                                 --rich-open asks the rich fields of the OPEN
+#                                 pull requests only, and emits every row in the
+#                                 --rich shape. A MERGED or CLOSED row carries
+#                                 checks:"unknown", mergeable:"unknown",
+#                                 review:"" and failing_checks:[] — the ABSENT
+#                                 values the Bitbucket arm already emits, which
+#                                 mean NOT ASKED and never "no checks".
+#                                 WHY: the four rich fields are verdicts about a
+#                                 PR's HEAD, and a terminal head is finished —
+#                                 no check will run against it and no review will
+#                                 change. Measured 2026-10-01 on this
+#                                 repository, `--rich --state all --limit 1000`
+#                                 took 43.0 s against 7.3 s without the rich
+#                                 fields, and all 1000 rows were terminal, so
+#                                 36 s bought answers nobody can use.
+#                                 Re-measured 2026-10-02 with 3 PRs open:
+#                                 `--rich --state open` 2.6-3.3 s, `--state all`
+#                                 8.6-10.5 s, the split read 12.2-13.5 s.
+#                                 ON GITHUB IT IS TWO CALLS and the terminal
+#                                 rows come from the plain one; a PR open in both
+#                                 payloads is emitted once, from the rich call.
+#                                 A FAILURE IN EITHER CALL PRINTS NO ROWS AND
+#                                 EXITS NON-ZERO — a half answer reported as
+#                                 whole is what would let a caller fold a store
+#                                 that lost every open PR.
+#                                 ON BITBUCKET IT ANSWERS EXACTLY AS --rich,
+#                                 because that arm asks the host no verdict: its
+#                                 rows are already `unknown` whatever the state,
+#                                 so there is no second call to save.
+#                                 THE CALLER STILL ASKS ONCE. One `pr-list`
+#                                 invocation is one host question however many
+#                                 calls this makes, so a caller's per-refresh
+#                                 arithmetic is unchanged.
+#                                 `--limit` BOUNDS EACH CALL, NOT THE UNION, so
+#                                 the row count can exceed it by up to the number
+#                                 of open pull requests. Measured 2026-10-02 with
+#                                 5 open: `--limit 5` answered 6 rows, where
+#                                 `--rich` answered 5 — the open call returned an
+#                                 open PR that fell outside the plain call's
+#                                 newest-5 page. It is NOT bounded per call and
+#                                 then trimmed, because trimming would drop
+#                                 either a verdict the rich call just bought or a
+#                                 terminal row the store needs, and the caller
+#                                 cannot say which. Harmless where `--limit`
+#                                 exceeds the open count, which is every caller
+#                                 today: the board asks 1000 against 5 open, and
+#                                 no other caller passes this flag.
 #                                 [--since <iso>] narrows the listing to pull
 #                                 requests the host has seen change since that
 #                                 stamp. Measured 2026-09-21 on this repository:
@@ -86,16 +133,19 @@
 #                                 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.
+#                                 BOTH HOSTS NARROW, BY DIFFERENT ROUTES.
+#                                 `gh pr list` takes `--search`. `bb pr list`
+#                                 has no query flag (verified against bb 1.9.0:
+#                                 `unknown flag: --query`), so a windowed
+#                                 Bitbucket listing goes through
+#                                 `bb_window_listing`, which asks REST with
+#                                 `q=state="..." AND updated_on>="..."` and
+#                                 walks every page. It refuses a window whose
+#                                 rows fall short of the server's `size` rather
+#                                 than printing it as whole: 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
@@ -471,11 +521,22 @@ die6() { echo "plot-host: $*" >&2; exit 6; }
 # secondary message contains the phrase *"rate limit"* too — *"You have
 # exceeded a secondary rate limit"* — so a quota test applied first claims
 # every secondary refusal and the distinction is lost at the point it is made.
-host_failure_kind() { # $1=stderr text → throttled|secondary|failed
+#
+# FOUR ANSWERS, NOT THREE — #1087: a GraphQL 504 matched neither limit pattern,
+# so it came back `failed`, and `failed` is the one kind a command fixes —
+# `gh auth login`, wrong advice for a server that took too long to answer.
+# `timeout` is anchored on the HTTP status word (`HTTP 50[234]`), never a bare
+# `\b504\b`, which would match a run id or a line count just as well. It runs
+# AFTER both limit arms: a rate-limit message that also carries a 5xx status
+# must stay `throttled`, because patience until the reset is the right advice
+# for it, and `timeout` would counsel exactly the wrong patience — none.
+host_failure_kind() { # $1=stderr text → secondary|throttled|timeout|failed
   if LC_ALL=C grep -qiE 'secondary rate|exceeded a secondary|abuse detection|abuse-detection|too many requests|\b429\b' <<<"$1"; then
     echo secondary
   elif LC_ALL=C grep -qiE 'rate limit|ratelimit' <<<"$1"; then
     echo throttled
+  elif LC_ALL=C grep -qiE "HTTP 50[234]|couldn.t respond to your request in time" <<<"$1"; then
+    echo timeout
   else
     echo failed
   fi
@@ -555,6 +616,16 @@ pr_list_failed() { # $1=stderr text
       echo "  or run against an account with quota left. No login will help." >&2
       exit 5
       ;;
+    timeout)
+      # NO REPAIR NAMED, FOR THE SAME REASON SECONDARY NAMES NONE — #1087. A
+      # 504 means the server took too long, not that the credential is bad, so
+      # `host_repair`'s `gh auth login` would send a reader to fix a login
+      # that was never broken. The decision is to ask again, not to log in.
+      echo "plot-host: pr-list: host timed out — ${err:-the host took too long and said nothing}" >&2
+      echo "  Nothing is wrong with the login: the server took too long to answer." >&2
+      echo "  The next refresh asks again." >&2
+      exit 3
+      ;;
   esac
   # THE ONE KIND A COMMAND FIXES. An auth gap and a DNS blip both land here, and
   # the repair for the first is a login this connector can name — see
@@ -2281,6 +2352,47 @@ tracker_scheme() {
   tracker_raw | awk '{print tolower($1)}'
 }
 
+# WHO ANSWERS THE OPEN-ISSUE LIST — the domain's answer, not this script's.
+#
+# `issue-list` and `issue-view` tested `tracker_scheme = jira` and sent every
+# other scheme to the git host. That test was a DRIFTED SECOND COPY of the rule:
+# measured 2026-10-01, `PLOT_HOST=github PLOT_TRACKER=linear issue-list` exited 0
+# having called `gh issue list`, so a repository tracking in Linear was shown
+# GitHub's issues under Linear's name — a list not wrong about any single row
+# and wrong about all of them.
+#
+# So the rule is ASKED rather than re-implemented. `issueSource` has eight unit
+# tests and the board already asks it (`fleet.ts:2369-2380`); a lister list in
+# shell would be the same copy one directory over, free to drift again the first
+# time a connector is added.
+#
+# THE ONE NODE HOP THIS SCRIPT MAKES, and the cost rule permits it: `plot-host.sh`
+# runs once per operator command or once per board PR refresh, never once per
+# agent per pass, and a shipped bundle answers in 39 ms
+# (`docs/shell-and-domain.md`).
+#
+# Prints the entry's line verbatim — `tracker\t<scheme>`, `git-host`, or
+# `nobody\t<reason>` — and exits 0. Exits 1, naming the entry, when the rule
+# CANNOT BE ASKED: no node, no bundle, a non-zero exit, or a word outside the
+# three. THAT CASE NEVER FALLS THROUGH TO THE GIT HOST — the fall-through is
+# the defect, and `an-outage-is-not-an-answer` is what a list saying *none*
+# because it could not ask reproduces.
+issue_source() {
+  local out rc
+  out="$(tracker_raw | node "$here/board/plot-issue-source.mjs" "$be" 2>/dev/null)"; rc=$?
+  if [ "$rc" -ne 0 ]; then
+    echo "plot-host: cannot ask board/plot-issue-source.mjs who lists this repository's issues (exit $rc); the question failed and the git host is not asked in its place" >&2
+    return 1
+  fi
+  case "${out%%$'\t'*}" in
+    tracker|git-host|nobody) printf '%s\n' "$out" ;;
+    *)
+      echo "plot-host: board/plot-issue-source.mjs answered '${out}', which is not one of tracker/git-host/nobody; the question failed and the git host is not asked in its place" >&2
+      return 1
+      ;;
+  esac
+}
+
 tracker_base_url() {
   # The base URL is the SECOND token; a bare `jira` with no URL yields "".
   # PLOT_JIRA_BASE_URL overrides, for a caller that has the URL separately.
@@ -2610,6 +2722,29 @@ bb_list_page_length() {
   esac
 }
 
+# A PAGE THAT IS PROVABLY WHOLE SAYS SO, and that sentence is the licence a
+# joining caller needs. This reported only truncation until 2026-10-02: a
+# complete page was SILENT, so a caller could not tell "this page holds every
+# PR" from "this adapter has no opinion", and the only reading left to it was
+# the page's own row count against its own limit. That is a coincidence rather
+# than evidence — measured on this repository, `--state all --limit 1000`
+# returned exactly 1000 rows of 1064 PRs, so the count-based test failed, the
+# scan's `.list-complete` was withheld, and every branch the join did not name
+# fell through to one `pr-state` call each: 26 calls at 3.8 s, 54-61% of the
+# scan's wall time in slice 1's five runs (#1017).
+#
+# THE CLAIM IS THE ADAPTER'S BECAUSE THE PAGING SEMANTICS ARE. Whether a short
+# page proves anything depends on how the host pages, which is exactly what
+# this script knows and a caller does not. `pr_sweep_report` already states its
+# own stronger claim in this shape and `plot-fleet-scan.sh` already reads that
+# sentence; this is the same contract for the second path, so a listing is no
+# longer the one answer a caller has to guess at.
+#
+# BOTH SENTENCES OR NEITHER. The complete and truncated reports are the two
+# outcomes of one decision, so they are emitted from one place: a reader can
+# never see both for one state, and silence now means only that no claim was
+# owed — no `--limit`, or an empty page.
+#
 # $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" len=""
@@ -2617,17 +2752,33 @@ pr_list_report_truncation() {
   [ "$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
+    # Measured 2026-10-02 on this repository (1064 PRs): `--limit 1100`
+    # answered 1065 rows and `--limit 2000` the same 1065, so a page short of
+    # its limit is the whole list and asking generously costs the rows that
+    # exist rather than the rows requested.
+    if [ "$count" -lt "$limit" ] 2>/dev/null; then pr_list_report_complete "$be" "$limit" "$state" "$count"; return 0; fi
   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
+    if [ -n "$len" ] && [ "$count" -lt "$len" ] 2>/dev/null; then pr_list_report_complete "$be" "$limit" "$state" "$count"; return 0; fi
   fi
   # 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
 }
 
+# THE WORDING IS A CONTRACT between this script and `plot-fleet-scan.sh`, pinned
+# on both sides exactly as `pr-list sweep complete` is. A page that cannot prove
+# itself whole never prints it, so a match is licence and a miss is silence —
+# never a guess.
+#
+# PER STATE, like the truncation report beside it, because the scan asks for two
+# states and joins both: a caller needs to know which pages were whole, not that
+# some were.
+pr_list_report_complete() { # $1 backend  $2 limit  $3 state word  $4 row count
+  echo "plot-host: $1 pr-list state=$3 page complete ($4 rows below requested limit $2) — this page holds every pull request the host has in this state" >&2
+}
+
 # The backends this script has an arm for, which is what "drivable" means here.
 #
 # THE LIST LIVES IN THE SCRIPT BECAUSE THE SCRIPT IS WHAT WOULD CHANGE. Adding a
@@ -3657,6 +3808,10 @@ case "$op" in
   pr-list)
     state="open"
     rich=0
+    # Whether the rich fields are asked of the OPEN pull requests only. Set by
+    # `--rich-open`, which also sets `rich`: the flag narrows what is ASKED and
+    # never what is emitted.
+    rich_open=0
     # PIN THE LIST TO ONE REPOSITORY, the same `--repo` `pr-state` and
     # `pr-merged` already take. A checkout may carry several remotes on several
     # hosts, and an unpinned `gh pr list` resolves whichever of them it prefers
@@ -3681,6 +3836,22 @@ case "$op" in
         --state) state="${2:?}"; shift 2 ;;
         --limit) limit="${2:?}"; shift 2 ;;
         --rich) rich=1; shift ;;
+        # THE RICH FIELDS OF THE OPEN PRs AND THE PLAIN FIELDS OF THE REST.
+        # Measured 2026-10-01 on this repository: `--rich --state all --limit
+        # 1000` took 43.0 s and the same call without the rich fields took 7.3 s,
+        # while all 1000 rows were terminal — so 36 s bought four verdicts about
+        # heads nobody can act on. Re-measured 2026-10-02 with 3 PRs open:
+        # `--rich --state open` is 2.6-3.3 s and `--state all` is 8.6-10.5 s.
+        #
+        # IT IMPLIES `--rich`, so every row carries every rich field and no
+        # consumer has to ask which call produced it. A terminal row's verdicts
+        # arrive at the ABSENT values the Bitbucket arm already emits, which the
+        # store's schema accepts — so no `PR_INDEX_VERSION` bump follows.
+        #
+        # THE SPLIT IS ONLY WORTH MAKING OVER A SET THAT HOLDS TERMINAL ROWS.
+        # With `--state open` asked, both calls would list the same PRs and the
+        # second would be waste, so this collapses to plain `--rich` there.
+        --rich-open) rich=1; rich_open=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:>"`,
@@ -3759,6 +3930,57 @@ case "$op" in
     fi
 
     if [ "$be" = "github" ]; then
+      # THE SPLIT READ, AND IT IS TWO CALLS BECAUSE THE COST IS PER ROW.
+      # `gh pr list` pages internally and takes no page-size flag, so 1000 rich
+      # rows cost 1000 rows' worth of `statusCheckRollup` whatever the page.
+      # Narrowing the SET is the only lever: the rich fields are asked of the
+      # open pull requests, and everything else comes back plain.
+      #
+      # ORDER MATTERS — THE RICH ROWS GO FIRST. A PR that is open appears in
+      # both payloads, and a consumer keyed by number takes the last line it
+      # read; the second call is filtered to the terminal states instead, so no
+      # number is emitted twice and no rich row is overwritten by a plain one.
+      # Filtered rather than ordered, because a caller that sorts or de-dupes
+      # differently must not be able to reach a different answer.
+      #
+      # ASKED ONLY WHERE THE SET CAN HOLD A TERMINAL ROW. With `--state open`
+      # the two calls would list the same PRs, so this collapses to `--rich`.
+      if [ "$rich_open" = 1 ] && [ "$state" != "open" ]; then
+        # THE OPEN HALF, RICH. Asked with the caller's own `--limit` and
+        # `--since`: a window the caller set applies to both halves, or the two
+        # would answer about different populations.
+        #
+        # `|| exit $?` ON BOTH, and the rule `pr_list_call`'s header states is
+        # what makes it load-bearing here too: this runs in a command
+        # substitution, so a `die` inside leaves only that subshell and the
+        # outer script would carry on with an empty payload. A failing open call
+        # and a failing all call must each exit non-zero and print no rows.
+        _rich_open_out="$("$0" pr-list --rich --state open \
+          ${limit:+--limit "$limit"} ${since:+--since "$since"} \
+          ${repo_args[1]+--repo "${repo_args[1]}"} \
+          $(for _b in $branches; do printf -- '--branch %s ' "$_b"; done))" || exit $?
+        # THE REST, PLAIN, AND THE TERMINAL ROWS ARE THE ONES KEPT. `--state
+        # all` is asked rather than merged+closed separately: GitHub answers it
+        # in one call, and two calls would double a cost this exists to halve.
+        _plain_all_out="$("$0" pr-list --state "$state" \
+          ${limit:+--limit "$limit"} ${since:+--since "$since"} \
+          ${repo_args[1]+--repo "${repo_args[1]}"} \
+          $(for _b in $branches; do printf -- '--branch %s ' "$_b"; done))" || exit $?
+        [ -n "$_rich_open_out" ] && printf '%s\n' "$_rich_open_out"
+        # THE ABSENT VALUES ARE THE BITBUCKET ARM'S, not invented here: a
+        # terminal row carries every field a rich row carries, so one shape
+        # reaches every consumer. `checks:"unknown"` means NOT ASKED and never
+        # *no checks* — the board's fold takes the verdict it already holds for
+        # the same number, and a row with none reads as unavailable.
+        #
+        # `draft`, `url` and `updatedAt` are REAL here — the plain GitHub arm
+        # asks for them — so only the four verdicts are absent.
+        [ -n "$_plain_all_out" ] && printf '%s\n' "$_plain_all_out" \
+          | jq -c 'select(.state=="MERGED" or .state=="CLOSED")
+              | . + {checks:"unknown", mergeable:"unknown", review:"",
+                     failing_checks:[]}'
+        exit 0
+      fi
       if [ "$rich" = 1 ]; then
         # `checks` has FOUR states, and two of them mean "a person is the
         # blocker" rather than "a machine is busy":
@@ -3898,12 +4120,25 @@ case "$op" in
               }'
         fi
       else
+        # `isDraft`, `url` AND `updatedAt` TRAVEL ON THE PLAIN ARM TOO, and they
+        # are cheap: measured 2026-09-21, `number,updatedAt` over 937 PRs is
+        # 4715 ms against 5417 ms for the base fields, where
+        # `statusCheckRollup` alone is 18 842 ms. They are scalar columns on the
+        # PR node; the rollup is a per-row resolution, and that is the whole
+        # 36 s `--rich-open` removes.
+        #
+        # ASKED HERE BECAUSE `--rich-open`'S TERMINAL ROWS COME THROUGH THIS
+        # ARM, and a terminal row must carry every field a rich row carries —
+        # `updatedAt` most of all, since it is the field a durable store
+        # advances its watermark by. Without it a split full read would leave
+        # the store unable to narrow and the daily full read would never fall
+        # due against anything but a cold window.
         _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,author)" || exit $?
+          --json number,title,state,headRefName,isDraft,url,updatedAt,author)" || exit $?
         pr_list_report_truncation github "$limit" "$state" \
           "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
         printf '%s' "$_gh_raw" \
-          | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,author:(.author.login // "")}'
+          | jq -c '.[] | {number:.number,title:.title,state:.state,head:.headRefName,draft:.isDraft,url:.url,updatedAt:(.updatedAt // ""),author:(.author.login // "")}'
       fi
     else
       # `author` IS THE `nickname`, the one handle field a Bitbucket user
@@ -4324,7 +4559,19 @@ case "$op" in
     done
     limit_args=()
     [ -n "$limit" ] && limit_args=(--limit "$limit")
-    if [ "$(tracker_scheme)" = "jira" ]; then
+    # WHO LISTS THESE ISSUES IS ASKED ONCE, HERE, BEFORE THE ARMS — after the
+    # argument parsing, so a caller's typo is still reported as a usage error
+    # rather than as a tracker refusal. The arms below then dispatch on the
+    # ANSWER, never on a second reading of the config.
+    source_said="$(issue_source)" || exit 1
+    if [ "${source_said%%$'\t'*}" = "nobody" ]; then
+      # Exit 4, the code this op already documents as *this host cannot be
+      # asked at all* — a configuration a person fixes, not a call to retry.
+      # NOTHING HAS BEEN SPENT: no `gh`, no `bb`, no curl has run yet.
+      echo "plot-host: ${source_said#*$'\t'}" >&2
+      exit 4
+    fi
+    if [ "$source_said" = $'tracker\tjira' ]; then
       # Jira, resolved through the REST API — DISPATCHED ON `Tracker`, never on
       # `backend()`: a Bitbucket repo tracking in Jira is the normal enterprise
       # case, so the git host is irrelevant here (see the Jira helpers up top).
@@ -4502,7 +4749,15 @@ case "$op" in
     # 4 to `unsupported` and anything else to `failed` must not need a second
     # table to read this op.
     num="${1:?issue-view needs an issue number}"; shift
-    if [ "$(tracker_scheme)" = "jira" ]; then
+    # Asked once, before the arms, exactly as issue-list does — the same
+    # question with the same three answers and the same exit codes. A consumer
+    # that maps 4 to `unsupported` needs no second table to read this op.
+    source_said="$(issue_source)" || exit 1
+    if [ "${source_said%%$'\t'*}" = "nobody" ]; then
+      echo "plot-host: ${source_said#*$'\t'}" >&2
+      exit 4
+    fi
+    if [ "$source_said" = $'tracker\tjira' ]; then
       # Jira, dispatched on `Tracker` not `backend()` — the same rule issue-list
       # follows. `num` is a Jira KEY (PROJ-123), read off issue-list moments ago.
       #

package/plot-monitor-subject.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Plot helper: the ONE answer to "is this monitor's subject still there?"
 #
-# SOURCED, NOT RUN, by `plot-worker-monitor.sh` and `plot-agent-monitor.sh`.
+# SOURCED, NOT RUN, by `plot-agent-monitor.sh` and `plot-build-monitor.sh`.
 # Both need the same computation and neither renders it the same way, which is
 # the same shape as `plot-worker-state.sh` and `plot-pr-merged.sh` — and the
 # same reason. `plot-worker-state.sh` carried five of its six states in
@@ -132,9 +132,19 @@ plot_monitor_subject() {
   pid=$(cat "$pid_file" 2>/dev/null | tr -d ' \n')
 
   # A file that exists but holds no digits is a half-written pid, which is the
-  # startup window caught mid-`printf`. Not gone.
+  # startup window caught mid-`printf`. Not gone — UNLESS the wrapper has
+  # already recorded an exit beside it. `start_worker` removes that record
+  # before every start, so in the startup window it is absent. A worker loop
+  # that moves to a new desk empties the pid file it leaves
+  # (`move_worker_record`), and the wrapper still writes the exit into this
+  # desk when the loop ends; without this arm a monitor watching that desk
+  # would read `starting` forever.
   case "$pid" in
-    '' | *[!0-9]*) printf 'starting'; return 0 ;;
+    '' | *[!0-9]*)
+      if [ -f "$(dirname "$pid_file")/.plot-worker.exit" ]; then
+        printf 'gone'; return 0
+      fi
+      printf 'starting'; return 0 ;;
   esac
 
   if kill -0 "$pid" 2>/dev/null; then
@@ -192,3 +202,45 @@ plot_monitor_wait() { # $1 = seconds to wait, $2 = pid file
   done
   return 0
 }
+
+# ═══════════════════════════════════════════════════════════════════════════
+# WHICH DESK A MONITOR WATCHES THIS PASS, AFTER A HOP MAY HAVE MOVED ITS AGENT
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# `PLOT_WORKTREE` is fixed at launch, but `update_manifest_on_hop` rewrites the
+# manifest's `worktree` field when the loop cuts a new desk — so a monitor that
+# never re-reads it watches the launch desk forever. This is the shell twin of
+# `watchedDesk` in `packages/domain/src/rules/desk-manifest.ts`, duplicated
+# rather than called for the reason `docs/shell-and-domain.md` gives: both
+# monitors re-read this every pass (30 s and 300 s), and a 39 ms bundle hop paid
+# on every pass forever is the cost the shell side exists to avoid.
+# `desk-manifest.corpus.test.ts` holds the pair; a disagreement stops the
+# branch rather than being adjusted away.
+#
+# `$1` = the manifest file this monitor was handed (`PLOT_MANIFEST_FILE`), may
+# be empty or absent.
+# `$2` = the desk this monitor was launched on (`PLOT_WORKTREE`).
+# Prints the desk to watch THIS pass.
+plot_watched_desk() { # $1 = manifest file, $2 = launch desk → prints the watched desk
+  local manifest_file="${1:-}" launched="${2:-}" field
+  # ABSENT IS NOT FALSE. No manifest file named, or one that is gone, both mean
+  # "watch what you were launched on" — never a crash and never "watch
+  # nothing". A hand-started monitor with no `PLOT_MANIFEST_FILE` is a supported
+  # shape, not an error.
+  if [ -n "$manifest_file" ] && [ -f "$manifest_file" ]; then
+    # Same grep-and-sed idiom `plot_manifest_for_worktree` uses: the manifest is
+    # pretty-printed one field per line, so this avoids parsing JSON in bash.
+    field=$(grep -m1 '"worktree":' "$manifest_file" 2>/dev/null | sed 's/.*"worktree": *"\([^"]*\)".*/\1/')
+  else
+    field=''
+  fi
+  # Whitespace-only reads as absent too, matching the rule: trim leading and
+  # trailing space before testing for emptiness.
+  field="${field#"${field%%[![:space:]]*}"}"
+  field="${field%"${field##*[![:space:]]}"}"
+  if [ -n "$field" ]; then
+    printf '%s' "$field"
+  else
+    printf '%s' "$launched"
+  fi
+}