@plot-pm/board 0.11.0 → 0.13.0

package/plot-host.sh

@@ -8,6 +8,17 @@
 #
 # Ops (the ~6 operations plot actually needs):
 #   backend                       print the resolved backend: github|bitbucket
+#                                 REPORTS WHAT THE REPO DECLARED. An
+#                                 unrecognised `Git host` word is NOT silently
+#                                 defaulted to github — that drove a repo
+#                                 declaring `gitlab` through `gh` until
+#                                 2026-09-08. A backend this script has no arm
+#                                 for exits 4 and names the word on stderr:
+#                                 exit 4 is "this backend has no answer at
+#                                 all", a configuration a person fixes rather
+#                                 than a transient to retry. Adding a host is
+#                                 an edit to `HOST_DRIVES` and the arms below,
+#                                 and to nothing in `packages/domain`.
 #   default-branch                print the repo's default branch name
 #   pr-state <number|branch> [--repo <owner/repo>]   one JSON object:
 #                                   {"number":N,"state":"OPEN|MERGED|CLOSED|NONE",
@@ -41,6 +52,12 @@
 #   pr-ready <number>              take a PR out of draft
 #                                 merge the PR
 #   pr-list [--state open|merged|closed|all] [--limit N] [--rich]
+#                                 [--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
+#                                 an unpinned list resolve the wrong one, and a
+#                                 caller joining it against `origin/*` refs then
+#                                 reads every branch as having no PR.
 #                                 JSON lines: {"number":N,"title":"...",
 #                                 "state":"...","head":"..."}
 #                                 --rich adds: draft, checks, mergeable, review,
@@ -122,10 +139,12 @@
 #   issue-list [--limit N]        open tracker issues as JSON lines:
 #                                 {"number":N,"title":"…","url":"…",
 #                                  "createdAt":"…"}
-#                                 READ-ONLY, and the only issue op here: Plot
-#                                 never writes to the tracker (no labels, no
-#                                 assignees, no close-on-merge), because a copy
-#                                 of tracker state ages into a lie.
+#                                 READ-ONLY. Plot writes no label, no assignee
+#                                 and no close-on-merge, because a copy of
+#                                 tracker state ages into a lie. The one write
+#                                 that exists is `issue-status`, and it records
+#                                 a status Plot itself just caused rather than
+#                                 mirroring one the tracker holds.
 #                                 `url` is "" when the host omits it, and a
 #                                 consumer renders the number as plain text
 #                                 rather than inventing an address — the rule
@@ -157,8 +176,8 @@
 #                                 tickets*, the failure this story is named for.
 #   issue-view <number>           ONE open issue as a single JSON object:
 #                                 {"number":N,"title":"…","body":"…","url":"…"}
-#                                 STILL READ-ONLY — the second issue op, and it
-#                                 reads. The board's *Create plan* action needs
+#                                 READ-ONLY — the second of the two issue reads.
+#                                 The board's *Create plan* action needs
 #                                 the issue's BODY as the problem statement, and
 #                                 issue-list deliberately omits it: the list is
 #                                 asked on a timer for every open issue, and a
@@ -183,6 +202,28 @@
 #                                 as issue-list. Jira answers 404 for a missing
 #                                 key, which is exit 3 here (the tracker moved),
 #                                 never an empty body.
+#   issue-status <key> <status>   THE ONE WRITE TO A TRACKER: record one status
+#                                 against one issue, and nothing else. No
+#                                 create, no close, no comment, no label — a
+#                                 plan referencing an issue is Plot's record,
+#                                 and the status is the single fact the tracker
+#                                 owns a copy of.
+#                                 JIRA ONLY. Exit 4 where `Tracker` is not jira:
+#                                 this adapter cannot be asked, which is neither
+#                                 a failure nor a silent success. The other
+#                                 vendor's projects surface is written by
+#                                 `plot-update-board.sh`, under its own
+#                                 credentials and through a different API — the
+#                                 reason the tracker port has two connectors.
+#                                 Prints `written` where the transition was
+#                                 performed and `no-target` where the workflow
+#                                 offers no such transition from the issue's
+#                                 current state — which is also what a repeated
+#                                 write reports, because the same status twice
+#                                 is the same status.
+#                                 The transition id is LOOKED UP, never guessed:
+#                                 ids are per workflow and per issue, so a
+#                                 hardcoded one writes to the wrong column.
 #   pr-body <number> --body B     replace the PR description
 #   rate-limit                    both GitHub budgets from `gh api rate_limit`.
 #                                 SUPERSEDED BY `limit`, and kept only because
@@ -336,6 +377,52 @@ host_failure_kind() { # $1=stderr text → throttled|secondary|failed
   fi
 }
 
+# --- the connector names its own repair -------------------------------------
+#
+# THE TEXT COMES FROM THE CONNECTOR THAT FAILED, never from a caller branching
+# on the stack. A refusal saying `gh auth login` is wrong advice on a Bitbucket
+# team, and it is wrong in the direction that costs most: a teammate who has not
+# read this repository runs the command they were given, it does nothing, and
+# the next step is to find a person. This connector already resolved its vendor
+# — `backend` above — so it is the one place that can name a CLI that exists.
+#
+# ONE FUNCTION RATHER THAN A TABLE AT EACH CALL SITE, and it is the connector
+# contract CLAUDE.md already states applied to words instead of budgets: only a
+# connector knows its account, its transport and its login command, so only a
+# connector may name them.
+#
+# A BACKEND THIS DOES NOT KNOW GETS NO ADVICE. Inventing a login command for an
+# unrecognised vendor is the same failure as naming the wrong one, so it says
+# what it does not know rather than guessing — the direction `host_failure_kind`
+# refuses in too.
+#
+# $1 = the backend word, as `backend` reported it.
+host_cli() { # → the CLI this backend drives, or '' where none is known
+  case "$1" in
+    github)    echo "gh" ;;
+    bitbucket) echo "bb" ;;
+    *)         echo "" ;;
+  esac
+}
+
+# The repair line for a host call that failed, on stderr, in this connector's
+# own words. Prints nothing where the vendor is unknown — see above.
+host_repair() { # $1=backend
+  local cli; cli="$(host_cli "$1")"
+  if [ -z "$cli" ]; then
+    echo "  Plot does not know which CLI drives '$1', so it cannot name the fix." >&2
+    echo "  Set 'Git host' in CLAUDE.md to a host Plot drives (github, bitbucket)." >&2
+    return
+  fi
+  if ! command -v "$cli" >/dev/null 2>&1; then
+    echo "  '$cli' is not on PATH, and this backend is driven through it." >&2
+    echo "  Install it, then: $cli auth login" >&2
+    return
+  fi
+  echo "  Check the CLI can answer: $cli auth status" >&2
+  echo "  If it is not logged in: $cli auth login" >&2
+}
+
 # A failed `pr-list`, reported and never swallowed.
 #
 # THREE OUTCOMES, KEPT APART — the rule `issue-list` states in full and this
@@ -350,13 +437,28 @@ pr_list_failed() { # $1=stderr text
   local err="$1"
   case "$(host_failure_kind "$err")" in
     secondary)
-      die6 "pr-list: host refused a burst — ${err:-the host refused the request and said nothing}"
+      # NO REPAIR NAMED, AND THAT IS THE ANSWER. A burst refusal clears in
+      # seconds and nothing is broken, so `$cli auth login` here would send a
+      # reader to fix a login that is already fine. The decision is the wait.
+      echo "plot-host: pr-list: host refused a burst — ${err:-the host refused the request and said nothing}" >&2
+      echo "  Nothing is wrong and nothing needs fixing: this limit bounds calls at" >&2
+      echo "  once, not per hour. Retry shortly, with fewer at a time." >&2
+      exit 6
       ;;
     throttled)
-      die5 "pr-list: host throttled — ${err:-the host refused the request and said nothing}"
+      echo "plot-host: pr-list: host throttled — ${err:-the host refused the request and said nothing}" >&2
+      echo "  The window's quota is spent. Wait for the reset the message names," >&2
+      echo "  or run against an account with quota left. No login will help." >&2
+      exit 5
       ;;
   esac
-  die3 "pr-list: ${err:-the host failed the request and said nothing}"
+  # 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
+  # `host_repair`, which asks the CLI this backend drives rather than assuming
+  # one. A failure that is neither costs the reader one `auth status`.
+  echo "plot-host: pr-list: ${err:-the host failed the request and said nothing}" >&2
+  host_repair "$(backend)"
+  exit 3
 }
 
 # Run one `pr-list` host call, or die reporting which failure it was.
@@ -556,7 +658,23 @@ jenkins_build_map() {
 # `LC_ALL=C` on the match: the CLI localises its messages, and a matcher that
 # only works in English would silently reclassify every miss as an outage for
 # anyone else.
+#
+# A MISSING CLI IS NOT A MISS, AND THE BARE `not found` ALTERNATIVE COULD NOT
+# TELL THEM APART. Measured 2026-09-06 with `gh` off `PATH`: the shell says
+# `bash: gh: command not found`, which matched — so `pr-merged` answered
+# `not-merged` where `plot-pr-merged.sh` answered `unaskable` about the same
+# branch. `not-merged` reads to `rules/landed.ts` as `none` (the host spoke and
+# said nothing merged), so `mayRemove` may permit a removal; `unaskable`
+# refuses. `plot-release-refs.sh` deletes remote refs on that answer and a
+# deleted ref is not re-creatable, so the two answers differ in the one
+# direction this estate has said it will not fail in.
+#
+# The bare alternative stays — it is what recognises a Bitbucket or Jira miss,
+# whose wording is neither `no pull requests found` nor `could not find`. What
+# it excludes is the shell's own phrasing for an absent binary, which is a
+# transport failure wearing a miss's words.
 is_lookup_miss() {
+  case "$1" in *'command not found'*) return 1 ;; esac
   LC_ALL=C grep -qiE 'no (pull request|pullrequest)s? (found|match)|could not find.*pull request|not found' <<<"$1"
 }
 
@@ -1179,7 +1297,10 @@ jira_require_config() {
     die3 "Tracker is jira but no base URL is configured (write 'Tracker: jira https://your.atlassian.net' or set PLOT_JIRA_BASE_URL)"
   fi
   if [ -z "${JIRA_EMAIL:-}" ] || [ -z "${JIRA_API_TOKEN:-}" ]; then
-    die3 "Jira needs JIRA_EMAIL and JIRA_API_TOKEN in the environment — an unauthenticated Jira must not read as an empty inbox"
+    echo "plot-host: Jira needs JIRA_EMAIL and JIRA_API_TOKEN in the environment — an unauthenticated Jira must not read as an empty inbox" >&2
+    echo "  Create a token at https://id.atlassian.com/manage-profile/security/api-tokens" >&2
+    echo "  then export JIRA_EMAIL=<your account email> and JIRA_API_TOKEN=<the token>." >&2
+    exit 3
   fi
 }
 
@@ -1302,21 +1423,64 @@ pr_list_report_truncation() {
   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
 }
 
-backend() {
+# 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
+# host means teaching the ops below its CLI; this array is the record of which
+# have been taught, and it sits beside the arms it describes. `packages/domain`
+# holds no copy — `HostBackend` is any string, and `host-shell.ts` passes
+# through whatever this prints — so a third host is an edit here and nowhere in
+# the domain.
+HOST_DRIVES="github bitbucket"
+
+# Is this a backend the ops below can actually drive?
+host_drivable() { # $1=backend word
+  case " $HOST_DRIVES " in *" $1 "*) return 0 ;; *) return 1 ;; esac
+}
+
+# The backend this repository declared, in the word it used.
+#
+# REPORTS WHAT IT WAS TOLD, AND DEFAULTS ONLY WHERE NOTHING WAS SAID. A repo
+# declaring `Git host: gitlab` was answered `github` until 2026-09-08 — the
+# unrecognised word was discarded and the default returned in its place, so a
+# GitLab team was driven through `gh` and every refusal named a host they had
+# not configured. An absent key still defaults to github, which is the same
+# answer for the same reason: nothing was said, so nothing was discarded.
+#
+# `bb` is an ALIAS rather than an unknown word, and it normalises to bitbucket.
+backend_declared() {
   if [ -n "${PLOT_HOST:-}" ]; then
-    case "$PLOT_HOST" in
-      github|bitbucket) echo "$PLOT_HOST"; return ;;
-      *) die "unknown PLOT_HOST '$PLOT_HOST' (github|bitbucket)" ;;
-    esac
+    printf '%s\n' "$PLOT_HOST" | tr '[:upper:]' '[:lower:]'
+    return
   fi
   local v
   v="$(bash "$here/plot-config.sh" get "Git host" "github" | tr '[:upper:]' '[:lower:]')"
   case "$v" in
-    bitbucket|bb) echo "bitbucket" ;;
-    *) echo "github" ;;
+    bb) echo "bitbucket" ;;
+    "") echo "github" ;;
+    *) printf '%s\n' "$v" ;;
   esac
 }
 
+# The resolved backend, refused where this script has no arm for it.
+#
+# THE REFUSAL IS THIS LAYER'S, AND IT NAMES THE WORD. Every op below dispatches
+# on this answer, so a word with no arm must stop here rather than fall into
+# whichever branch happens to be last — that is how `gitlab` became a Bitbucket
+# call. Exit 4 says the question cannot be asked of this backend AT ALL, which
+# is what an unknown host is: not a broken call to retry, but a configuration a
+# person must fix. `host-shell.ts` reads that code as `unaskable` and reads the
+# sentence below for the name.
+backend() {
+  local v
+  v="$(backend_declared)" || return 1
+  if ! host_drivable "$v"; then
+    echo "plot-host: cannot drive '$v' — this script drives ${HOST_DRIVES// /, }; set the 'Git host' key in CLAUDE.md (or \$PLOT_HOST) to one of them" >&2
+    return 4
+  fi
+  printf '%s\n' "$v"
+}
+
 
 # --- the connector counts what it spends -----------------------------------
 #
@@ -1756,7 +1920,11 @@ jen() {
 
 op="${1:-}"; [ -n "$op" ] || die "usage: plot-host.sh <op> [args...] (see header)"
 shift
-be="$(backend)" || exit 1
+# THE BACKEND'S REFUSAL IS PASSED THROUGH, NOT FLATTENED. `backend` exits 4 for
+# a host it has no arm for, and exit 4 is the contract's "this backend has no
+# answer at all" — the one code every caller reads as permanent rather than
+# transient. Collapsing it to 1 here would tell a GitLab repo to retry forever.
+be="$(backend)" || exit $?
 
 # EVERY GITHUB OP CONSULTS THE ROUTER, ONCE, HERE. `gh_route` is asked before
 # the op runs and its answer is read from `$route` by whichever arm needs it —
@@ -2067,6 +2235,13 @@ case "$op" in
   pr-list)
     state="open"
     rich=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
+    # — so a caller comparing `origin/*` refs would join its refs against
+    # another repository's PRs and report every branch as having none. The
+    # caller knows which remote its refs came from; this op cannot guess it.
+    repo_args=()
     # `gh pr list` and `bb pr list` both cap at 30 by default. That is invisible
     # with --state open (few repos have 30 open PRs) and bites immediately with
     # --state all, where the newest 30 crowd out every older merged PR. A caller
@@ -2078,6 +2253,7 @@ case "$op" in
         --state) state="${2:?}"; shift 2 ;;
         --limit) limit="${2:?}"; shift 2 ;;
         --rich) rich=1; shift ;;
+        --repo) repo_args=(-R "${2:?}"); shift 2 ;;
         *) die "pr-list: unknown arg $1" ;;
       esac
     done
@@ -2107,7 +2283,11 @@ case "$op" in
       jen_instance=$(bash "$here/plot-config.sh" get "Jenkins instance" "" 2>/dev/null || echo "")
       [ -n "$jen_instance" ] || jen_instance="${JENKINS_INSTANCE:-}"
       if [ -z "$jen_instance" ]; then
-        die3 "CI is jenkins but no Jenkins instance is configured (set a 'Jenkins instance' key)"
+        echo "plot-host: CI is jenkins but no Jenkins instance is configured" >&2
+        echo "  Add a 'Jenkins instance' key to the ## Plot Config section of CLAUDE.md," >&2
+        echo "  naming the instance \`jen\` knows, or set JENKINS_INSTANCE." >&2
+        echo "  Or drop the 'CI: jenkins' key to read build status from the git host." >&2
+        exit 3
       fi
       jen_payload=$(jenkins_build_map "$jen_instance")
       jen_status=$(printf '%s' "$jen_payload" | jq -r '.status // "failed"' 2>/dev/null || echo "failed")
@@ -2196,7 +2376,7 @@ 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 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[@]}"} \
             --json number,title,state,headRefName,isDraft,mergeable,mergeStateStatus,reviewDecision,url)" || exit $?
           pr_list_report_truncation github "$limit" "$state" \
             "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
@@ -2225,7 +2405,7 @@ case "$op" in
               }'
         else
           # GitHub without Jenkins (or Jenkins not configured): use GitHub rollup
-          _gh_raw="$(pr_list_call gh 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[@]}"} \
             --json number,title,state,headRefName,isDraft,statusCheckRollup,mergeable,mergeStateStatus,reviewDecision,url)" || exit $?
           pr_list_report_truncation github "$limit" "$state" \
             "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
@@ -2256,7 +2436,7 @@ case "$op" in
               }'
         fi
       else
-        _gh_raw="$(pr_list_call gh 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[@]}"} \
           --json number,title,state,headRefName)" || exit $?
         pr_list_report_truncation github "$limit" "$state" \
           "$(jq 'length' <<<"$_gh_raw" 2>/dev/null || echo 0)"
@@ -2296,7 +2476,7 @@ case "$op" in
           # the GitHub arm uses, which is why it lives above the backend branch.
           # `bb`'s standing `unknown` becomes a real value where Jenkins answers.
           for _s in $bb_states; do
-            _bb_raw="$(pr_list_call bb pr list --state "$_s" --json)" || exit $?
+            _bb_raw="$(pr_list_call bb ${repo_args[@]+"${repo_args[@]}"} pr list --state "$_s" --json)" || exit $?
             pr_list_report_truncation bitbucket "$limit" "$_s" \
               "$(jq 'length' <<<"$_bb_raw" 2>/dev/null || echo 0)"
             printf '%s' "$_bb_raw" \
@@ -2325,7 +2505,7 @@ case "$op" in
         else
           # Bitbucket without Jenkins: checks remain unknown
           for _s in $bb_states; do
-            _bb_raw="$(pr_list_call bb pr list --state "$_s" --json)" || exit $?
+            _bb_raw="$(pr_list_call bb ${repo_args[@]+"${repo_args[@]}"} pr list --state "$_s" --json)" || exit $?
             pr_list_report_truncation bitbucket "$limit" "$_s" \
               "$(jq 'length' <<<"$_bb_raw" 2>/dev/null || echo 0)"
             printf '%s' "$_bb_raw" \
@@ -2334,7 +2514,7 @@ case "$op" in
         fi
       else
         for _s in $bb_states; do
-          _bb_raw="$(pr_list_call bb pr list --state "$_s" --json)" || exit $?
+          _bb_raw="$(pr_list_call bb ${repo_args[@]+"${repo_args[@]}"} pr list --state "$_s" --json)" || exit $?
           pr_list_report_truncation bitbucket "$limit" "$_s" \
             "$(jq 'length' <<<"$_bb_raw" 2>/dev/null || echo 0)"
           printf '%s' "$_bb_raw" \
@@ -2690,6 +2870,55 @@ case "$op" in
     fi
     ;;
 
+  issue-status)
+    # THE ONE WRITE TO A TRACKER, and the amendment this op records: Plot writes
+    # a STATUS to the tracker it was told about, and writes nothing else. No
+    # ticket is created, none is closed, no comment, label or assignee is
+    # touched. A plan referencing an issue stays Plot's record; the status is
+    # the one fact the tracker owns a copy of, because it is the one a person
+    # reads in the tracker rather than in Plot.
+    #
+    # JIRA ONLY, and deliberately so rather than by omission. This vendor's
+    # projects surface has a script of its own (`plot-update-board.sh`) reached
+    # by its own connector, and the two write through different APIs under
+    # different credentials — which is why the tracker port has two connectors
+    # rather than one arm with a branch. A repo whose `Tracker` is not jira gets
+    # exit 4 here: this adapter cannot be asked, which is not a failure and not
+    # a silent success.
+    #
+    # IDEMPOTENT BY NATURE. The same status written twice is the same status,
+    # and Jira answers a transition to the state an issue already holds by
+    # naming no such transition — which this reports as `no-target` rather than
+    # as a failure.
+    key="${1:?issue-status needs an issue key}"; shift
+    want="${1:?issue-status needs a status}"; shift
+    [ "$(tracker_scheme)" = "jira" ] || exit 4
+    jira_require_config
+    # THE TRANSITION IS LOOKED UP, NEVER GUESSED. Jira transitions are per
+    # workflow and per issue: the id for "In Progress" differs between projects
+    # and the transition may not be available from the issue's current state at
+    # all. A hardcoded id writes a status to the wrong column silently.
+    raw="$(jira_curl "/rest/api/2/issue/$key/transitions")"; curl_rc=$?
+    body_json="$(jira_check "$raw" "$curl_rc")" || exit $?
+    tid="$(printf '%s' "$body_json" | jq -r --arg want "$want" \
+      '[.transitions[]? | select((.name // "" | ascii_downcase) == ($want | ascii_downcase)
+                                 or ((.to.name // "" | ascii_downcase) == ($want | ascii_downcase)))]
+       | .[0].id // ""')"
+    if [ -z "$tid" ]; then
+      # NO SUCH TRANSITION IS AN ANSWER, not a failure. The tracker was reached
+      # and holds nowhere to put this status — either the workflow has no such
+      # state or the issue is already in it. Reporting it as a failure would
+      # make a repeated write look like an outage.
+      printf '%s\n' 'no-target'
+      exit 0
+    fi
+    raw="$(jira_curl "/rest/api/2/issue/$key/transitions" \
+             -X POST -H 'Content-Type: application/json' \
+             --data "$(jq -cn --arg id "$tid" '{transition:{id:$id}}')")"; curl_rc=$?
+    jira_check "$raw" "$curl_rc" >/dev/null || exit $?
+    printf '%s\n' 'written'
+    ;;
+
   pr-body)
     num="${1:?pr-body needs a PR number}"; shift
     body=""
@@ -2955,6 +3184,6 @@ case "$op" in
     ;;
 
   *)
-    die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|pr-body|rate-limit|limit|ci-limit|spend-rate)"
+    die "unknown op '$op' (backend|default-branch|pr-state|pr-create|pr-merge|pr-list|issue-list|issue-view|issue-status|pr-body|rate-limit|limit|ci-limit|spend-rate)"
     ;;
 esac

package/plot-monitor-subject.sh

@@ -0,0 +1,194 @@
+#!/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`.
+# 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
+# duplicate until 2026-08-18, and the copies had already drifted on the sixth.
+# Two monitors deciding independently when to stop would drift the same way, and
+# the failure would be silent: one monitor left running forever while its twin
+# exits is exactly the leak this file exists to close, half-fixed.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# WHY A MONITOR NEEDS THIS AT ALL
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# Measured 2026-08-30 and written up in
+# `docs/research/2026-08-30-what-ends-a-monitor.md`: **nothing ended a monitor.**
+# On an ordinary finish and on a `Worker bound` timeout alike, the wrapper's
+# `wait "$agent"` returns, the wrapper writes `.plot-worker.exit` and exits, and
+# both monitors are re-parented to `init` and loop forever. 34 of 40 monitors on
+# the machine were `ppid=1` at the time of measurement, and 100 forks cost
+# 23.3 ms against 4.8 ms on a quiet estate.
+#
+# The one run whose monitors WERE terminated is explained in that document and
+# is not a mechanism: `nohup` does not `setsid`, so an orphan keeps the
+# DISPATCHING SHELL's process group and a group kill sweeps it up collaterally.
+# That fires when a human closes a terminal and never when a worker finishes —
+# the opposite of a lifetime.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# THE SUBJECT IS THE AGENT, AND THAT IS THE WHOLE DESIGN
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# A monitor exists to watch a dispatched agent. When that agent is gone there is
+# nothing left to measure, so the monitor has finished its job rather than been
+# interrupted — which is why this is a MEASUREMENT and not a timer.
+#
+# The plan forbids a timer explicitly, and the measurement says why: *"a monitor
+# exiting after N seconds regardless would pass the visible assertions and
+# destroy the property the whole plan rests on — a monitor that stops publishing
+# means something."* A monitor that stops because its subject stopped carries
+# information. One that stops because a clock ran out carries none, and is
+# indistinguishable from one that crashed.
+#
+# THE AGENT COVERS ALL THREE ENDINGS. `--stop` kills the agent
+# (`plot-dispatch.sh:752`); the `Worker bound` kills the agent
+# (`plot-worker-loop.sh:172`); an ordinary finish is the agent exiting. In every
+# case the wrapper survives just long enough to write `.plot-worker.exit` and
+# then exits too. So watching the agent is sufficient, and watching the WRAPPER
+# would be wrong: the wrapper outlives the agent by design, and a monitor bound
+# to it would publish about a desk whose agent left.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# AN ABSENT PID FILE IS `starting`, NEVER `gone`
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# `plot-dispatch.sh:478` records a sub-millisecond gap in which the wrapper has
+# started and `.plot-worker.pid` is not yet written. The monitors start INSIDE
+# that window — they are backgrounded before the agent, deliberately, so they
+# exist before their subject does.
+#
+# So a monitor that read an absent pid file as `gone` would exit immediately on
+# every single dispatch, and the leak would be replaced by a monitor that never
+# runs. That is worse than the bug: an absent monitor is invisible, where an
+# orphaned one at least shows up in `ps`.
+#
+# Three answers, not two:
+#
+#   starting   no pid file yet, or an unreadable one — the wrapper has not
+#              written it. Keep going; say nothing.
+#   alive      the pid file names a process that exists. Keep going.
+#   gone       the pid file names a process that does not exist. Stop.
+#
+# `starting` and `alive` are both "keep going", and they are kept apart anyway
+# because the reason differs and a caller reporting them identically would lose
+# the distinction the startup window depends on.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# THE LOWER BOUND IS THE CALLER'S, AND IT IS AN ORDERING
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# The plan requires a monitor to outlive its agent long enough to record its
+# finding — the Attaching slice's property, which this slice must not eat. This
+# file does not enforce that, because it cannot: it answers a question and
+# renders nothing.
+#
+# What enforces it is the ORDER in the callers: publish the pass, THEN ask.
+# Every monitor therefore gets one final published pass after its agent has
+# gone, which is the lower bound expressed as sequence rather than as a sleep.
+# A caller that asked first and published second would satisfy the upper bound
+# and silently lose the lower one — so the order is asserted in the tests, not
+# left to a comment.
+
+# `kill -0` is the liveness question, and it is the same one
+# `plot-worker-state.sh` asks. It sends no signal; it only reports whether the
+# pid can be signalled. A pid we do not own answers EPERM rather than ESRCH,
+# which `kill -0` still reports as success — correct here, since a process we
+# cannot signal is nonetheless a process that exists.
+#
+# `$1` = the path to the agent's pid file (`.plot-worker.pid`).
+# Prints exactly one of: starting | alive | gone
+plot_monitor_subject() {
+  local pid_file="${1:-}" pid
+
+  # No path at all: a hand-run monitor with no worktree, which has no subject to
+  # outlive and must not exit on its first pass. `starting` is the honest answer
+  # — there is nothing here that says the subject is gone.
+  [ -n "$pid_file" ] || { printf 'starting'; return 0; }
+
+  # NO PID FILE SPLITS TWO CASES, and reading them as one is what made monitors
+  # immortal. `starting` is right only while the desk is still there and the
+  # wrapper has not yet written the pid. If the DIRECTORY the pid file lives in
+  # is gone, the desk was removed — there is no subject to wait for and none is
+  # coming, so the honest answer is `gone`.
+  #
+  # Measured on CI 2026-08-31: 14 monitors at PPID 1, aged 11-13 minutes, each
+  # holding a `sleep 1`, after every test in the reconcile suite had PASSED.
+  # A test's fixture is removed at teardown, so its pid file vanishes BEFORE the
+  # agent does; `plot_monitor_wait` then never sees `gone` and loops forever,
+  # holding node's event loop open until the job ceiling kills it. That is the
+  # whole of the reconcile-suite hang, and it is why this is a two-case answer
+  # rather than one.
+  #
+  # PRODUCTION IS UNCHANGED: a real worktree outlives its agent, so the
+  # directory is present and this reads `starting` exactly as before.
+  if [ ! -f "$pid_file" ]; then
+    [ -d "$(dirname "$pid_file")" ] && { printf 'starting'; return 0; }
+    printf 'gone'; return 0
+  fi
+
+  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.
+  case "$pid" in
+    '' | *[!0-9]*) printf 'starting'; return 0 ;;
+  esac
+
+  if kill -0 "$pid" 2>/dev/null; then
+    printf 'alive'
+  else
+    printf 'gone'
+  fi
+}
+
+# Sleep up to `$1` seconds, but stop early the moment the subject at `$2` is
+# gone. Returns 0 to publish another pass, 1 to leave.
+#
+# ═══════════════════════════════════════════════════════════════════════════
+# WHY THE WAIT IS SPLIT WHEN THE PUBLISHING IS NOT
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# THE TWO CADENCES MUST STAY APART. The plan is explicit: the WorkerMonitor
+# samples the process table every 30 s because a CPU delta is meaningless
+# sampled further apart, and the AgentMonitor asks the host every 300 s because
+# this repo has already measured what host questions on a fast loop cost. *"One
+# subject wants tight sampling of a cheap fact; the other occasional sampling of
+# an expensive one. Merging them would force one of those two to be wrong."*
+#
+# SO ONLY THE WAIT IS SPLIT, NEVER THE PASS. Publishing still happens on the
+# monitor's own interval, unchanged — nothing here makes the AgentMonitor ask
+# the host more often, and its 300 s stays 300 s. What is split is the IDLE TIME
+# between passes, into short naps with a `kill -0` between them.
+#
+# WITHOUT THIS, THE UPPER BOUND IS THE INTERVAL. An AgentMonitor checking only
+# after its full sleep would outlive an agent that finished in ten seconds by
+# nearly five minutes. Bounded, technically — and still an orphan on every
+# dispatch, on an estate where dispatches are frequent. The measurement that
+# opened this slice counted 34 orphans; a five-minute window would have counted
+# plenty too.
+#
+# THE PROBE IS FREE, WHICH IS WHY IT MAY BE FREQUENT. `kill -0` sends no signal
+# and asks no host — it is a single syscall against the process table, the same
+# question `plot-worker-state.sh` asks. The expensive half of an AgentMonitor
+# pass is the host round trip, and that is in the PASS, not here.
+#
+# THE NAP IS THE GRANULARITY, and one second is chosen against the WorkerMonitor
+# rather than in the abstract: a monitor may not outlive its agent by more than
+# the tighter of the two cadences, or the fast monitor's exit would be slower
+# than its own sampling. Any interval SHORTER than one nap sleeps once and is
+# unaffected, which keeps `PLOT_MONITOR_INTERVAL=1` in a test behaving exactly
+# as it reads.
+plot_monitor_wait() { # $1 = seconds to wait, $2 = pid file
+  local remaining="${1:-0}" pid_file="${2:-}" nap
+  while [ "$remaining" -gt 0 ]; do
+    nap=1
+    [ "$remaining" -lt 1 ] && nap="$remaining"
+    sleep "$nap" || return 1
+    remaining=$((remaining - nap))
+    [ "$(plot_monitor_subject "$pid_file")" = gone ] && return 1
+  done
+  return 0
+}