@plot-pm/board 0.16.2 → 0.17.0

package/plot-monitor-subject.sh

@@ -1,14 +1,13 @@
 #!/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.
+# SOURCED, NOT RUN, by `plot-agent-monitor.sh`. 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. A monitor
+# deciding independently when to stop, with its computation copied rather than
+# shared, would drift the same way, and the failure would be silent: a monitor
+# left running forever is exactly the leak this file exists to close.
 #
 # ═══════════════════════════════════════════════════════════════════════════
 # WHY A MONITOR NEEDS THIS AT ALL
@@ -132,9 +131,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 +201,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
+}

package/plot-plan-meta.sh

@@ -130,14 +130,19 @@
 #                  `<!-- deferred -->` (bare, no colon) sets the flag with no
 #                  reason; `waves[].branches[].deferred_reason` carries the
 #                  sentence after the colon, "" where none was written.
-#                  `<!-- waits: bug/other -->` names ONE branch this branch
-#                  waits on, reported as `waves[].branches[].waits_on`. The key
-#                  is ABSENT where no annotation was written — never "" — and
-#                  the value is a branch name in this repo, not a plan slug and
-#                  not a cross-repo reference. The parser reports what the file
-#                  says: a prerequisite no plan declares still parses, and the
-#                  scan is what turns that into a verdict. `waits:` and
-#                  `deferred:` are independent — a branch may carry both.
+#                  `<!-- waits: bug/other -->` names branches this branch waits
+#                  on, reported as `waves[].branches[].waits_on`, A LIST, in the
+#                  line's order, duplicates removed — several `<!-- waits: … -->`
+#                  comments on one line, or one `<!-- waits: x, y -->`, give the
+#                  same list. The key is ABSENT where no annotation was written
+#                  — never `[]` — and each value is a branch name in this repo,
+#                  not a plan slug and not a cross-repo reference. The parser
+#                  reports what the file says: a prerequisite no plan declares
+#                  still parses, and the scan is what turns that into a verdict.
+#                  `waits:` and `deferred:` are independent — a branch may carry
+#                  both. A `waits:` value the parser cannot read as a branch, on
+#                  a line that names one, is reported in `unread_waits[]`
+#                  instead — never dropped silently.
 #                  `<!-- builds: normalizeVersion, a shared helper -->` names
 #                  what this slice BUILDS, reported as
 #                  `waves[].branches[].builds`. OPTIONAL, like `Sprint:` and
@@ -208,6 +213,14 @@
 #                  heading, which carries no `Branch:`. Covers both slice
 #                  consumers, so a heading lost to the first-heading latch
 #                  (#1042) is named too. ALWAYS present; [] when none.
+#   unread_waits   `{ branch, value }` pairs, in document order, for a `waits:`
+#                  marker on a line that names a branch whose value the parser
+#                  could not read as one — a report, not a refusal. The marker
+#                  is dropped from `waits_on` rather than silently discarding
+#                  it: a plan documenting the annotation as prose on a line with
+#                  no branch stays silent, since reporting that would fire on
+#                  every such plan. A marker inside a code span is quoted, not
+#                  written, and is read nowhere. ALWAYS present; [] when none.
 #   issues         tracker issue numbers this plan answers, from the `## Status`
 #                  `Issue:` line or front matter `issue:` (sorted, unique).
 #                  A DEDICATED field, never a scan of the body for `#NNN`: a
@@ -294,7 +307,7 @@ if [ ${#files[@]} -eq 0 ] && [ ${#missing[@]} -eq 0 ]; then
 fi
 
 for f in ${missing[@]+"${missing[@]}"}; do
-  printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"unread_branch_headings":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
+  printf '{"file":"%s","format":"none","error":"file not found","phase_raw":"","phase":"NONE","phase_alt_raw":"","phase_alt":"NONE","type":"","title":"","sprint":"","story":"","assignee":"","branches":[],"prs":[],"issues":[],"malformed_prs":[],"changelog":[],"long_wave_names":[],"unread_branch_headings":[],"unread_waits":[],"review_raw":"","review":"NONE","impl_raw":"","impl":"NONE","design_raw":"","approved_raw":"","released_raw":"","delivered_raw":"","started_raw":[]}\n' \
     "$(printf '%s' "$f" | sed 's/\\/\\\\/g; s/"/\\"/g')"
 done
 
@@ -332,6 +345,53 @@ function jesc(s) {
   return s
 }
 function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+# Every `<!-- waits: … -->` marker on a line, each value split on commas, in
+# the line order with duplicates removed, written into outArr/outN (outN is
+# outArr[0] — awk scalars are pass-by-value, so a count returned through a
+# parameter needs an array slot instead). A value that does not look like a
+# branch name is appended to the global pending_unread_value[] instead of
+# outArr, with its count in pending_unread_n; the caller (the branch match
+# below, which alone knows the branch this line names) drains it into
+# unread_waits_branch[]/unread_waits_value[].
+#
+# BWK awk (macOS) and POSIX awk elsewhere have no `match(s, re, arr)` and no
+# `gensub` — both gawk-only. So this loops with plain `match()` plus `substr()`
+# over the remainder of the line, the same technique the rest of this parser
+# already uses for `prs` and `issues`.
+#
+# A MARKER INSIDE A CODE SPAN IS QUOTED, NOT WRITTEN: Markdown renders it as
+# text, so it annotates nothing. Spans are removed before the search. Measured
+# on `main`: `2026-09-01-a-slice-can-wait-on-another-plan.md` quotes
+# `<!-- waits: <branch> -->` on its own branch line, and without this strip it
+# reported as an unread wait.
+function parse_waits(s, outArr,   raw, parts, np, i, seen, n_out) {
+  n_out = 0
+  delete pending_unread_value; pending_unread_n = 0
+  gsub(/`[^`]*`/, "", s)
+  while (match(s, /<!--[ \t]*waits:[ \t]*/)) {
+    s = substr(s, RSTART + RLENGTH)
+    raw = s
+    sub(/-->.*$/, "", raw)
+    np = split(trim(raw), parts, /[ \t]*,[ \t]*/)
+    for (i = 1; i <= np; i++) {
+      if (parts[i] == "") continue
+      if (parts[i] !~ "^(" PREFIXES ")/[^ \t,]+$") pending_unread_value[++pending_unread_n] = parts[i]
+      else if (!(parts[i] in seen)) outArr[++n_out] = parts[i]
+      seen[parts[i]] = 1
+    }
+  }
+  outArr[0] = n_out
+  return n_out
+}
+# The value of the LAST `<!-- key: value -->` marker on a line, trimmed, the
+# text up to its closing `-->`. `key` is a regex alternation (`deferred|moved`).
+# Both slice dialects read `claimed:`, `deferred:`, `builds:` and `agent:`
+# through this one reader. Each caller keeps its own presence test.
+function marker_value(s, key) {
+  sub("^.*<!--[ \t]*(" key "):[ \t]*", "", s)
+  sub(/[ \t]*-->.*$/, "", s)
+  return trim(s)
+}
 # Value after the first colon, stripped of bold markers / quotes / space.
 function val_after_colon(s) {
   sub(/^[^:]*:/, "", s); sub(/^\**[ \t]*/, "", s)
@@ -442,14 +502,15 @@ function reset_state() {
   delete wave_names; delete wave_of; delete wave_seq; delete wave_count
   delete deferred_of; delete deferred_why; delete claimed_of; delete ordered_b; n_waves = 0
   delete branch_heading
-  delete waits_of; delete waits_set
+  delete waits_of; delete waits_set; delete waits_n
+  delete unread_waits_branch; delete unread_waits_value; n_unread_waits = 0
   delete builds_of; delete builds_set
   delete agent_of; delete agent_set
   delete started; n_started = 0
   fm_changelog = ""
   delete changelog; n_changelog = 0; changelog_seen = 0; cl_open = 0
 }
-function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assignee, review, impl, design, approved, delivered, issue, issue2, i, j, v, is_dup, out, sorted_b, sorted_p, sorted_i, nb, np, ni, num_issues, str_issues, n_num_i, n_str_i, issue_is_str) {
+function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assignee, review, impl, design, approved, delivered, issue, issue2, i, j, k, v, is_dup, out, sorted_b, sorted_p, sorted_i, nb, np, ni, num_issues, str_issues, n_num_i, n_str_i, issue_is_str) {
   # THE PHASE IS READ FROM THE FIELD PLOT WRITES. A canonical `State:`/`Phase:`
   # outranks front matter, because every lifecycle script writes the canonical
   # body and none writes front matter: `plot-approve.sh` holds zero front-matter
@@ -615,11 +676,18 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
       out = out (first ? "" : ",") "{\"branch\":\"" jesc(ordered_b[i]) "\",\"deferred\":" deferred_of[i] \
             ",\"deferred_reason\":\"" jesc(deferred_why[i]) "\"" \
             ",\"claimed\":\"" jesc(claimed_of[i]) "\""
-      # ABSENT, NOT EMPTY, where no prerequisite was declared. The key appears
-      # only on a branch whose line carries a `waits:` annotation, so a consumer
-      # reading `waits_on` gets a branch name or nothing — never a blank string
-      # that reads as a prerequisite with no name.
-      if (waits_set[i] == 1) out = out ",\"waits_on\":\"" jesc(waits_of[i]) "\""
+      # ABSENT, NOT EMPTY ARRAY, where no prerequisite was declared. The key
+      # appears only on a branch whose line carries a `waits:` annotation, so a
+      # consumer reading `waits_on` gets a list of one or more names or no key
+      # at all — never `[]`, which would read as a declared wait on nothing.
+      # waits_of is flattened as waits_of[i,k] (k = 1..waits_n[i]) since this
+      # awk has no nested arrays; store_waits() fills it per branch, in
+      # document order, duplicates removed.
+      if (waits_set[i] == 1) {
+        out = out ",\"waits_on\":["
+        for (k = 1; k <= waits_n[i]; k++) out = out (k > 1 ? "," : "") "\"" jesc(waits_of[i, k]) "\""
+        out = out "]"
+      }
       # ABSENT, NOT EMPTY, for the same reason `waits_on` is: a slice that
       # names no deliverable emits no key, so a consumer reads a name or
       # nothing. An empty string would read as a deliverable called "".
@@ -672,6 +740,17 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
     }
   }
   out = out "]"
+  # unread_waits[]: a `waits:` marker on a branch line whose value the parser
+  # could not read as a branch, `{ branch, value }` in document order — a
+  # report, not a refusal. Filled by store_waits() as each branch is matched;
+  # a `waits:` syntax example on a PROSE line (no branch claim) never reaches
+  # store_waits(), so it stays silent, as today.
+  out = out ",\"unread_waits\":["
+  for (i = 1; i <= n_unread_waits; i++) {
+    out = out (i > 1 ? "," : "") "{\"branch\":\"" jesc(unread_waits_branch[i]) "\"" \
+          ",\"value\":\"" jesc(unread_waits_value[i]) "\"}"
+  }
+  out = out "]"
   out = out ",\"review_raw\":\"" jesc(review) "\",\"review\":\"" norm_review(review) "\""
   out = out ",\"impl_raw\":\"" jesc(impl) "\",\"impl\":\"" norm_impl(impl) "\""
   out = out ",\"design_raw\":\"" jesc(design) "\""
@@ -703,6 +782,24 @@ function note_branch_heading(   h) {
   sub(/[ \t]*<!--.*$/, "", h)
   branch_heading[n_waves] = h
 }
+# Copies the line-local waits list parse_waits() just filled (line_waits[],
+# line_waits[0] = count) into the flattened per-branch storage, and drains
+# pending_unread_value[] — the values parse_waits() could not read as a branch
+# — into unread_waits_branch[]/unread_waits_value[], now that the branch this
+# line claims (n = n_branches, b = the branch) is known. Called from both
+# slice dialects at the moment each claims a branch, so a `waits:` syntax
+# example on a line with NO branch claim never drains the queue and stays
+# silent — the same rule the old single-value reading followed.
+function store_waits(n, b,   k) {
+  waits_n[n] = line_waits[0] + 0
+  for (k = 1; k <= waits_n[n]; k++) waits_of[n, k] = line_waits[k]
+  waits_set[n] = (waits_n[n] > 0) ? 1 : 0
+  for (k = 1; k <= pending_unread_n; k++) {
+    unread_waits_branch[++n_unread_waits] = b
+    unread_waits_value[n_unread_waits] = pending_unread_value[k]
+  }
+  delete pending_unread_value; pending_unread_n = 0
+}
 # The longest wave name that still reads as a label, not prose. A JUDGEMENT, not
 # a measurement: the longest legitimate name in the estate is `Offered first`
 # (13), and the offender this exists to catch is a 53-character sentence, so the
@@ -978,13 +1075,7 @@ section == "slices" && slice_shape != "heading" {
   # a reflection, not the claim: git refs remain authoritative. Computed before
   # the branch loop below — match() clobbers RSTART/RLENGTH, which that loop
   # needs to advance.
-  claim_note = ""
-  if (index($0, "claimed:") > 0) {
-    _c = $0
-    sub(/^.*<!--[ \t]*claimed:[ \t]*/, "", _c)
-    sub(/[ \t]*-->.*$/, "", _c)
-    claim_note = trim(_c)
-  }
+  claim_note = (index($0, "claimed:") > 0) ? marker_value($0, "claimed") : ""
   # THE REASON FOR THE DEFERRAL, and not merely the fact of one.
   #
   # `<!-- deferred: verified already implemented 2026-08-17 — startRepair() at
@@ -1013,24 +1104,19 @@ section == "slices" && slice_shape != "heading" {
   # The two words differ in what they tell a READER — given up, versus taken
   # somewhere else — and the reason is kept verbatim, so the distinction is not
   # lost by being read alike.
-  defer_note = ""
-  if (index($0, "deferred:") > 0 || index($0, "moved:") > 0) {
-    _d = $0
-    sub(/^.*<!--[ \t]*(deferred|moved):[ \t]*/, "", _d)
-    sub(/[ \t]*-->.*$/, "", _d)
-    defer_note = trim(_d)
-  }
-  # THE PREREQUISITE THIS BRANCH NAMES: `<!-- waits: bug/other-branch -->`.
+  defer_note = (index($0, "deferred:") > 0 || index($0, "moved:") > 0) ? marker_value($0, "deferred|moved") : ""
+  # THE PREREQUISITES THIS BRANCH NAMES: `<!-- waits: bug/other-branch -->`.
   #
-  # ONE branch, never a list. A slice needing two prerequisites has not been cut
-  # finely enough, and a list invites a dependency graph nobody wants to debug.
-  # The greedy `.*` takes the LAST annotation when a line carries two, which is
-  # the same rule `deferred:` and `claimed:` already follow.
+  # A LIST, not one name. Several `<!-- waits: … -->` comments on a line, or one
+  # `<!-- waits: x, y -->`, give the same list in document order, duplicates
+  # removed — see parse_waits(). The old greedy `sub()` took only the LAST
+  # annotation when a line carried two, which silently dropped every other
+  # prerequisite a slice had cleared for merge eligibility by itself (#1153).
   #
-  # The value is a BRANCH NAME, so it stops at the first whitespace rather than
-  # running to the closing marker the way a deferral reason does: a reason is a
-  # sentence, a branch name is a token, and trailing prose inside the comment
-  # would silently become part of a name that then matches nothing.
+  # Each value is a BRANCH NAME, so it stops at the first whitespace or comma
+  # rather than running to the closing marker the way a deferral reason does: a
+  # reason is a sentence, a branch name is a token, and trailing prose inside
+  # the comment would silently become part of a name that then matches nothing.
   #
   # `deferred:` is a judgement and `waits:` is a checkable fact, so the two are
   # separate annotations and both may sit on one line. Read here, beside the
@@ -1039,7 +1125,15 @@ section == "slices" && slice_shape != "heading" {
   #
   # `has_waits` carries presence separately from the value, because ABSENT and
   # EMPTY are different answers — a branch declaring no prerequisite emits no
-  # `waits_on` key at all.
+  # `waits_on` key at all, never `[]`.
+  #
+  # A value that does not look like a branch is NOT dropped — parse_waits()
+  # queues it in pending_unread_value[], and once the branch this line claims is
+  # known (below), it is copied into unread_waits_branch[]/unread_waits_value[].
+  # A line with no branch claim never drains the queue, so a `waits:` syntax
+  # example in prose — not on a branch line — stays silent, as today.
+  delete line_waits
+  has_waits = (parse_waits($0, line_waits) > 0)
   # WHAT THIS SLICE BUILDS: `<!-- builds: normalizeVersion, a shared helper -->`.
   #
   # AN ANNOTATION, NOT A FIELD LINE, and that is what makes it work in BOTH
@@ -1064,35 +1158,8 @@ section == "slices" && slice_shape != "heading" {
   # `has_builds` carries presence separately from the value, exactly as
   # `waits:` does: a slice declaring nothing emits no key, so a consumer reads
   # a deliverable or nothing and never a blank string that looks like one.
-  builds_note = ""
-  has_builds = 0
-  if ($0 ~ /<!--[ \t]*builds:[ \t]*/) {
-    _bl = $0
-    sub(/^.*<!--[ \t]*builds:[ \t]*/, "", _bl)
-    sub(/[ \t]*-->.*$/, "", _bl)
-    builds_note = trim(_bl)
-    if (builds_note != "") has_builds = 1
-  }
-  waits_note = ""
-  has_waits = 0
-  if ($0 ~ /<!--[ \t]*waits:[ \t]*/) {
-    _w = $0
-    sub(/^.*<!--[ \t]*waits:[ \t]*/, "", _w)
-    sub(/[ \t].*$/, "", _w)
-    sub(/-->.*$/, "", _w)
-    waits_note = trim(_w)
-    # THE VALUE MUST LOOK LIKE A BRANCH, and that check is what keeps a
-    # SYNTAX EXAMPLE from becoming a declaration. A plan that documents the
-    # annotation writes the literal marker in prose, and no comment-aware
-    # reading can tell that apart from the real thing on the same line — the
-    # branch prefixes can. `<branch>` is not a branch name; `bug/x` is.
-    #
-    # Reusing the branch prefixes rather than a new pattern: the prerequisite
-    # IS a branch in this repo, so the two must never disagree about what a
-    # branch name looks like.
-    if (waits_note ~ "^(" PREFIXES ")/[^ \t]+$") has_waits = 1
-    else waits_note = ""
-  }
+  builds_note = ($0 ~ /<!--[ \t]*builds:[ \t]*/) ? marker_value($0, "builds") : ""
+  has_builds = (builds_note != "")
   # WHICH KIND OF AGENT THIS SLICE NEEDS: `<!-- agent: reviewer -->`.
   #
   # `--agent <name>` was the only selector and only an operator could type it.
@@ -1122,15 +1189,8 @@ section == "slices" && slice_shape != "heading" {
   # `has_agent` carries presence separately from the value, as all three
   # annotations before it do: a slice naming no kind emits no key, so dispatch
   # reads a name or nothing and never a blank string that looks like one.
-  agent_note = ""
-  has_agent = 0
-  if ($0 ~ /<!--[ \t]*agent:[ \t]*/) {
-    _ag = $0
-    sub(/^.*<!--[ \t]*agent:[ \t]*/, "", _ag)
-    sub(/[ \t]*-->.*$/, "", _ag)
-    agent_note = trim(_ag)
-    if (agent_note != "") has_agent = 1
-  }
+  agent_note = ($0 ~ /<!--[ \t]*agent:[ \t]*/) ? marker_value($0, "agent") : ""
+  has_agent = (agent_note != "")
   # ONE LIST ITEM, AT MOST ONE CLAIM — an `if`, not the `while` this was.
   #
   # The old loop walked the line taking every backticked name on it, which is
@@ -1164,10 +1224,10 @@ section == "slices" && slice_shape != "heading" {
     # Claim reflection, written by the worker after its ref push succeeds. This
     # is a reflection, not the claim: git refs remain authoritative.
     claimed_of[n_branches] = claim_note
-    # The prerequisite travels with the branch. Presence is tracked separately
-    # so a branch that declares none emits no key.
-    waits_of[n_branches] = waits_note
-    waits_set[n_branches] = has_waits
+    # The prerequisites travel with the branch, flattened as waits_of[n,1..k]
+    # since this awk has no nested arrays. Presence is tracked separately so a
+    # branch that declares none emits no key.
+    store_waits(n_branches, b)
     builds_of[n_branches] = builds_note
     builds_set[n_branches] = has_builds
     # The kind travels with the branch, presence tracked separately so a slice
@@ -1231,13 +1291,7 @@ section == "slices" && slice_shape == "heading" {
 
   # Claim/deferral annotations bind to the line carrying the branch name, which
   # is the heading. Read before any match() below, which clobbers RSTART/RLENGTH.
-  claim_note = ""
-  if (index($0, "claimed:") > 0) {
-    _c = $0
-    sub(/^.*<!--[ \t]*claimed:[ \t]*/, "", _c)
-    sub(/[ \t]*-->.*$/, "", _c)
-    claim_note = trim(_c)
-  }
+  claim_note = (index($0, "claimed:") > 0) ? marker_value($0, "claimed") : ""
   # `moved:` IS THE SAME ANSWER AS `deferred:`, and CLAUDE.md has said so since
   # the reconcile scan was written: *"`deferred:`/`moved:` in the plan means
   # reapable"*. `plot-reconcile-scan.sh:504` matches both in one arm; this
@@ -1249,16 +1303,7 @@ section == "slices" && slice_shape == "heading" {
   # The two words differ in what they tell a READER — given up, versus taken
   # somewhere else — and the reason is kept verbatim, so the distinction is not
   # lost by being read alike.
-  defer_note = ""
-  if (index($0, "deferred:") > 0 || index($0, "moved:") > 0) {
-    _d = $0
-    sub(/^.*<!--[ \t]*(deferred|moved):[ \t]*/, "", _d)
-    sub(/[ \t]*-->.*$/, "", _d)
-    defer_note = trim(_d)
-  }
-  # The prerequisite, read exactly as the list-item spelling reads it. Both
-  # dialects emit the same waves[], so a field added to one only would break
-  # that contract the first time a plan migrated.
+  defer_note = (index($0, "deferred:") > 0 || index($0, "moved:") > 0) ? marker_value($0, "deferred|moved") : ""
   # WHAT THIS SLICE BUILDS: `<!-- builds: normalizeVersion, a shared helper -->`.
   #
   # AN ANNOTATION, NOT A FIELD LINE, and that is what makes it work in BOTH
@@ -1283,48 +1328,20 @@ section == "slices" && slice_shape == "heading" {
   # `has_builds` carries presence separately from the value, exactly as
   # `waits:` does: a slice declaring nothing emits no key, so a consumer reads
   # a deliverable or nothing and never a blank string that looks like one.
-  builds_note = ""
-  has_builds = 0
-  if ($0 ~ /<!--[ \t]*builds:[ \t]*/) {
-    _bl = $0
-    sub(/^.*<!--[ \t]*builds:[ \t]*/, "", _bl)
-    sub(/[ \t]*-->.*$/, "", _bl)
-    builds_note = trim(_bl)
-    if (builds_note != "") has_builds = 1
-  }
-  waits_note = ""
-  has_waits = 0
-  if ($0 ~ /<!--[ \t]*waits:[ \t]*/) {
-    _w = $0
-    sub(/^.*<!--[ \t]*waits:[ \t]*/, "", _w)
-    sub(/[ \t].*$/, "", _w)
-    sub(/-->.*$/, "", _w)
-    waits_note = trim(_w)
-    # THE VALUE MUST LOOK LIKE A BRANCH, and that check is what keeps a
-    # SYNTAX EXAMPLE from becoming a declaration. A plan that documents the
-    # annotation writes the literal marker in prose, and no comment-aware
-    # reading can tell that apart from the real thing on the same line — the
-    # branch prefixes can. `<branch>` is not a branch name; `bug/x` is.
-    #
-    # Reusing the branch prefixes rather than a new pattern: the prerequisite
-    # IS a branch in this repo, so the two must never disagree about what a
-    # branch name looks like.
-    if (waits_note ~ "^(" PREFIXES ")/[^ \t]+$") has_waits = 1
-    else waits_note = ""
-  }
+  builds_note = ($0 ~ /<!--[ \t]*builds:[ \t]*/) ? marker_value($0, "builds") : ""
+  has_builds = (builds_note != "")
+  # The prerequisites, read exactly as the list-item spelling reads them — see
+  # parse_waits() and the comment at the list-item block for why the value is a
+  # list, why it stops at whitespace/comma, and how an unreadable value reaches
+  # unread_waits instead of being dropped.
+  delete line_waits
+  has_waits = (parse_waits($0, line_waits) > 0)
   # The agent kind, read exactly as the list-item spelling reads it. Both
   # dialects emit the same waves[], so a field added to one only would break that
   # contract the first time a plan migrated. See the list-item block for why the
   # value runs to the closing marker and why this one cannot validate itself.
-  agent_note = ""
-  has_agent = 0
-  if ($0 ~ /<!--[ \t]*agent:[ \t]*/) {
-    _ag = $0
-    sub(/^.*<!--[ \t]*agent:[ \t]*/, "", _ag)
-    sub(/[ \t]*-->.*$/, "", _ag)
-    agent_note = trim(_ag)
-    if (agent_note != "") has_agent = 1
-  }
+  agent_note = ($0 ~ /<!--[ \t]*agent:[ \t]*/) ? marker_value($0, "agent") : ""
+  has_agent = (agent_note != "")
 
   # The branch is the `Branch:` value, matched against the known prefixes exactly
   # as the old shape matched the backticked name. Written unquoted in the heading
@@ -1351,8 +1368,7 @@ section == "slices" && slice_shape == "heading" {
     deferred_of[n_branches] = ($0 ~ /<!--[ \t]*(deferred|moved)[ \t]*(:|-->)/) ? "true" : "false"
     deferred_why[n_branches] = defer_note
     claimed_of[n_branches] = claim_note
-    waits_of[n_branches] = waits_note
-    waits_set[n_branches] = has_waits
+    store_waits(n_branches, b)
     builds_of[n_branches] = builds_note
     builds_set[n_branches] = has_builds
     agent_of[n_branches] = agent_note

package/plot-pr-merged.sh

@@ -70,6 +70,19 @@
 # Both halves are pinned in `test/reconcile/host.test.mjs`, so the exemption
 # rests on tests that fail when it stops being true.
 #
+# AN EMPTY BRANCH IS NOT ASKED ABOUT. `gh pr list --head ""` applies no filter,
+# so every PR in the repository matches: measured 2026-10-01 on `origin/main`
+# (`56a978ea`), `_plot_merged_lookup ""` answered `found`, `pr_merged ""` exited
+# 0 — merged — and `pr_merged_heads ""` printed 98 lines, the head of every
+# merged PR here. So each of the three lookups refuses an empty branch BEFORE
+# `command -v gh`, answering `unaskable` rather than `none` because a lookup that
+# did not run is silence and `none` would claim the host spoke; `pr_open ""` then
+# casts no veto, which is safe only because `pr_merged ""` refuses on the same
+# branch, as `mayRemove` asserts. The guard sits here and not at the call sites:
+# all five callers guard it today and that is precisely why the defect stayed
+# latent, so a sixth caller omitting the guard would be told a ref may be
+# deleted.
+#
 # `mergedAt` IS READ, NEVER `state`. A merged PR reports state CLOSED, and
 # trusting `state` would refuse every squash-merged branch — which is the whole
 # population these scripts exist for. Squash-merge rewrites the commits, so the
@@ -122,6 +135,7 @@ _plot_landed() {
 # is silence, and silence is never permission.
 _plot_merged_lookup() {
   local br="$1" out
+  [ -n "$br" ] || { echo unaskable; return; }
   command -v gh >/dev/null 2>&1 || { echo unaskable; return; }
   out=$(gh pr list --head "$br" --state all --limit 100 --json mergedAt 2>/dev/null) \
     || { echo unaskable; return; }
@@ -131,6 +145,7 @@ _plot_merged_lookup() {
 # What the host says about an OPEN PR on this branch: found / none / unaskable.
 _plot_open_lookup() {
   local br="$1" out
+  [ -n "$br" ] || { echo unaskable; return; }
   command -v gh >/dev/null 2>&1 || { echo unaskable; return; }
   out=$(gh pr list --head "$br" --state open --limit 1 --json number 2>/dev/null) \
     || { echo unaskable; return; }
@@ -195,6 +210,7 @@ pr_open() {
 # merged.
 pr_merged_heads() {
   local br="$1" out
+  [ -n "$br" ] || return 1
   command -v gh >/dev/null 2>&1 || return 1
   out=$(gh pr list --head "$br" --state all --limit 100 --json mergedAt,headRefOid 2>/dev/null) \
     || return 1