@plot-pm/board 0.11.0 → 0.13.0

package/plot-fleet-scan.sh

@@ -177,12 +177,29 @@
 # crashed pulse costs nothing — the next pulse re-derives the truth. Nothing
 # here creates a branch, pushes a ref, or starts a worker.
 #
-# ONE exception to "writes nothing": --log-pulse appends a pulse line to each
-# reported plan (see below). That is a LOG, not state — deleting the whole log
-# changes no behaviour, because the next run re-derives everything. The flag
-# defaults OFF precisely so internal callers (plot-implement, plot-dispatch,
-# which invoke --next) can never amend a plan as a side effect of asking what
-# to work on; /plot-fleet, the human-facing command, passes it every run.
+# TWO exceptions to "writes nothing", and NEITHER IS STATE. The test both pass
+# is the same one: delete what they wrote and no behaviour changes, because the
+# next run re-derives everything.
+#
+# 1. --log-pulse appends a pulse line to each reported plan (see below). That is
+#    a LOG. The flag defaults OFF precisely so internal callers (plot-implement,
+#    plot-dispatch, which invoke --next) can never amend a plan as a side effect
+#    of asking what to work on; /plot-fleet, the human-facing command, passes it
+#    every run.
+#
+# 2. `.plot/state/last-pulse.json` — the bridge, written by `write_bridge` on
+#    the success path of `--stream` (what the board spawns) and `--log-pulse`
+#    (what /plot-pulse passes). Those are the two callers that produce a pulse
+#    for somebody to READ; plain `--json` is a query and records nothing. That
+#    is a CACHE WITH AN EXPIRY: `pulse-bridge.ts` discards it after 15 minutes
+#    and on a version mismatch, so it can only ever be a shortcut to an answer
+#    this script re-derives anyway. It is machine-local and gitignored.
+#
+#    Added 2026-09-06. The board wrote this file and the scan did not, so a
+#    repository with no board had nothing to diff against and every pulse read
+#    as the first one — while `DESIGN-process.md` §1 requires the fleet to work
+#    with no board at all. The component that PRODUCES a pulse is the one that
+#    records it.
 #
 # Wave eligibility (the one rule this script encodes):
 #   A wave is ELIGIBLE when every non-deferred branch in every PRIOR wave is
@@ -217,13 +234,30 @@ why_nothing=0
 loose=0
 log_pulse=0
 as_json=0
+# Whether the JSON document is ASSEMBLED, which is not the same question as
+# whether it is PRINTED. `--json`/`--stream` need it to print; `--log-pulse`
+# needs it to write the bridge and prints prose. Measured 2026-09-06 on this
+# estate: assembling it costs 14.7 s against 5.9 s for prose alone, because the
+# branch objects carry `merge-tree` conflict sets. So the two meanings are
+# separated rather than folded, and a plain `/plot-fleet-scan.sh` pays neither.
+build_doc=0
+# Whether this run RECORDS the pulse it produced — `.plot/state/last-pulse.json`.
+# A third question again: `--json` assembles a document and records nothing,
+# because it is a query. Only the two callers that produce a pulse for somebody
+# to read set this — `--stream` (the board) and `--log-pulse` (/plot-pulse).
+record=0
 stream=0
 slug=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --no-fetch|--offline) do_fetch=0 ;;
     --loose) loose=1 ;;
-    --log-pulse) log_pulse=1 ;;
+    # `--log-pulse` ALSO ASSEMBLES THE DOCUMENT, because this is the flag that
+    # means *this pulse records itself*. It already appends a line to each plan;
+    # it now also writes `.plot/state/last-pulse.json`, so `/plot-pulse` in a
+    # repository with no board accumulates the history a delta needs. Without
+    # that, every pulse on a boardless repo is a first one forever.
+    --log-pulse) log_pulse=1; build_doc=1; record=1 ;;
     --next) next_only=1 ;;
     --list-eligible) next_only=1; list_all=1 ;;
     # THE SECOND QUESTION, and it borrows `--next`'s population deliberately.
@@ -231,8 +265,17 @@ while [ $# -gt 0 ]; do
     # about the SAME plans `--next` was silent over — a terminal plan admitted
     # here would answer `not-yet` about work somebody decided was not needed.
     --why-nothing) next_only=1; why_nothing=1 ;;
-    --json) as_json=1 ;;
-    --stream) as_json=1; stream=1 ;;
+    # `--json` ASSEMBLES BUT DOES NOT RECORD, and the two flags differ here for
+    # a reason. `--stream` is what the BOARD spawns (`fleet.ts:2694`) and
+    # `--log-pulse` is what `/plot-pulse` passes: both produce a pulse somebody
+    # is reading, so both record one. Plain `--json` is a machine-readable
+    # QUERY — `--next`'s neighbours ask it to find out what to work on — and a
+    # query that left a file behind would make the scan write on a path no
+    # caller asked to record. Two reconcile tests assert exactly that and
+    # caught this: `conflicts: the scan writes NOTHING` and `fleet: scan is
+    # read-only`, both of which drive `--json`.
+    --json) as_json=1; build_doc=1 ;;
+    --stream) as_json=1; stream=1; build_doc=1; record=1 ;;
     -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
     *) slug="$1" ;;
   esac
@@ -248,11 +291,13 @@ PREFIX_RE=$(cfg "Branch prefixes" "idea/, feature/, bug/, docs/, infra/" \
   | tr -d ' ' | tr ',' '\n' | sed 's#/$##' | grep -v '^$' | paste -sd'|' -)
 [ -n "$PREFIX_RE" ] || PREFIX_RE="idea|feature|bug|docs|infra"
 
+# `default_branch` repairs an unresolvable origin/HEAD before answering. The
+# scan derives every branch's state from `origin/<main>`, so a symref naming a
+# branch that does not exist makes every one of them unreadable at once.
+# shellcheck source=plot-default-branch.sh
+. "$script_dir/plot-default-branch.sh"
 MAIN=$(cfg "Main branch")
-if [ -z "$MAIN" ]; then
-  MAIN=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')
-fi
-[ -n "$MAIN" ] || MAIN="main"
+[ -n "$MAIN" ] || MAIN=$(default_branch)
 
 # A FAILED FETCH IS A FACT, not a shrug. The old line was
 # `git fetch ... 2>/dev/null` with its status discarded: a GitHub 503, a
@@ -1044,8 +1089,16 @@ terminal_learn() { # $1=branch $2=state
 # branch that is live — in flight, claimed, or with work on the floor — never
 # arrives here and therefore cannot be cached however the cache is filled. The
 # invariant is structural rather than a check that could be forgotten.
+#
+# SETS `_merged_by_host_state` TO THE WORD IT DECIDED ON, and that is what the
+# readings carry. The boolean is still the answer to this function's own
+# question; the word is what `branch_readings` reports, because the rule needs
+# to tell `CLOSED` from `NONE` from `-` and a yes/no cannot. Set before every
+# return, so a caller reading it never sees the previous branch's answer.
+_merged_by_host_state='-'
 merged_by_host() { # $1=branch → 0 when the host reports its PR MERGED
   local st
+  _merged_by_host_state='-'
   # Git has already been consulted to get here (no ref) and `terminal_cached`
   # asks it again about the plan and the tip. Only the round trip is skipped.
   if st=$(terminal_cached "$1"); then
@@ -1058,11 +1111,13 @@ merged_by_host() { # $1=branch → 0 when the host reports its PR MERGED
     # It is re-derived, not merely echoed: reaching here means git was asked
     # again this pass and still agrees — no ref, same plan, same tip.
     terminal_learn "$1" "$st"
+    _merged_by_host_state="$st"
     [ "$st" = "MERGED" ]
     return
   fi
   st=$(host_pr_state "$1" --ask)
   terminal_learn "$1" "$st"
+  _merged_by_host_state="$st"
   [ "$st" = "MERGED" ]
 }
 
@@ -1114,33 +1169,19 @@ reached_review() { # $1=branch → 0 when an open or merged PR exists
 # the branch it was cut from, which is why `plot-pr-merged.sh` reads PRs and not
 # refs, and why this reads the same source.
 #
-# THREE ANSWERS, and the third is the one that must not be collapsed into the
-# second:
-#
-#   | host says        | answer    | meaning                                  |
-#   |------------------|-----------|------------------------------------------|
-#   | MERGED           | ""        | cleared — the annotation stops mattering |
-#   | OPEN or CLOSED   | waiting   | a wait with an end                       |
-#   | NONE             | blocked   | no PR ever existed: a typo               |
-#   | `-` (unreachable)| waiting   | silence is not evidence, in EITHER       |
-#   |                  |           | direction: not permission to start, and  |
-#   |                  |           | not proof of a typo                      |
-#
-# A CLOSED, UNMERGED PR IS `waiting` RATHER THAN `blocked`: the host has seen
-# the branch, so nothing is misspelled — somebody withdrew the work, and that
-# resolves by reopening it, not by editing the plan.
-waits_state() { # $1=prerequisite branch → "waiting" | "blocked" | ""
-  local st
-  # `--ask` because the prerequisite is precisely the branch the repo-wide list
-  # may legitimately omit: its plan may be delivered and its ref gone. The
-  # bound is the same one PR #216 set — ABSENT branches, not all branches — and
-  # the cache above keeps it at one call per run.
-  st=$(host_pr_state "$1" --ask)
-  case "$st" in
-    MERGED) printf '' ;;
-    NONE)   printf 'blocked' ;;
-    *)      printf 'waiting' ;;
-  esac
+# WHAT THE HOST SAID, AND NOT WHAT IT MEANS. This function answered
+# `waiting` / `blocked` / `""` until the derivation moved: the three answers and
+# the reason `NONE` is the only one that means `blocked` are `waitVerdict` in
+# `packages/domain/src/rules/branch-state.ts`, with a test per case. What stays
+# here is the READING and the cost argument above it, which is a fact about
+# this script's host budget rather than about what a wait means.
+#
+# `--ask` because the prerequisite is precisely the branch the repo-wide list
+# may legitimately omit: its plan may be delivered and its ref gone. The bound
+# is the same one PR #216 set — ABSENT branches, not all branches — and the
+# cache above keeps it at one call per run.
+waits_pr_state() { # $1=prerequisite branch → OPEN|MERGED|CLOSED|NONE|-
+  host_pr_state "$1" --ask
 }
 
 # Modification time of a path, in epoch seconds, following symlinks — or "" when
@@ -3004,8 +3045,39 @@ EOF
   echo "$total $n"
 }
 
-branch_state() {
-  local br="$1"
+# WHAT WAS READ OF ONE BRANCH — ten tab-separated fields, and no decision.
+#
+# `branch_state()` UNTIL THIS SLICE, and every line of git archaeology below is
+# its own, unchanged. What went is the `if` chain that merged these readings
+# into a state word: that lives in `@plot-pm/domain`'s `branchState`, which the
+# caller asks once per plan through `plot-branch-state.mjs`. The script gathers;
+# the rule decides.
+#
+# THE REF CHECK STAYS IN FRONT, and it still does its job here. It is no longer
+# a `return`, so the ordering is preserved a different way: `mergeSubjectFound`
+# is READ ONLY where there is no ref, and reported `false` otherwise. See the
+# comment on that reading below — it is the same argument the returns carried.
+#
+# `-` IS THE ABSENT MARKER, per the field-order rule the caller documents: a
+# run of tabs collapses into one separator under `read`, so no field is ever
+# empty. Nothing here is optional, so nothing can shift.
+#
+# EIGHT FIELDS, NOT TEN. The two the plan states — the prerequisite's name and
+# what the host said about it — are appended by the caller, because reading the
+# second costs a host round trip and the scan spends it only where it could
+# change the answer. The rule reports which states those are; see the caller.
+#
+# THE DEFAULT BRANCH'S TIP IS READ ONCE PER RUN, not once per branch. It does
+# not move while the scan runs — every fact below is derived from the ref batch
+# taken at the start — and `remote_ref_oid` forks an `awk`, so asking per branch
+# would put one process per branch back on the 5 s pulse path. That is the
+# per-branch tail this script has repeatedly been thinned to remove.
+MAIN_TIP=$(remote_ref_oid "$MAIN")
+[ -n "$MAIN_TIP" ] || MAIN_TIP="-"
+
+branch_readings() { # $1=branch $2=deferred → eight tab-separated readings
+  local br="$1" _bs_deferred="$2" _bs_subject=false _bs_ahead=0 _bs_real=0 _bs_tip
+  local _bs_main="$MAIN_TIP"
   # THE REF CHECK STAYS IN FRONT. DO NOT HOIST THE MERGE LOOKUP ABOVE IT.
   #
   # A branch name can be reused: merge `bug/flaky`, delete it, then recreate it
@@ -3016,9 +3088,16 @@ branch_state() {
   #
   # The merge lookup is safe only BY PLACEMENT — it lives in the no-ref arm,
   # and a recreated branch has a ref, so it never reaches the lookup and takes
-  # the ancestry path below instead. Moving the lookup to the top reads like a
-  # cheap early answer and would silently report in-flight work as `merged`,
-  # opening the next wave on it. A test in fleet.test.mjs pins this ordering.
+  # the ancestry path below instead. Moving the lookup out of this `if` reads
+  # like a cheap early answer and would silently report in-flight work as
+  # `merged`, opening the next wave on it. A test in fleet.test.mjs pins this
+  # ordering, and `branch-state.test.ts` pins what the rule makes of it.
+  #
+  # THE PLACEMENT IS NOW A READING RATHER THAN A RETURN, and it holds the same
+  # way: a branch WITH a ref reports `mergeSubjectFound=false` whatever main
+  # says about its name, so the stale subject never reaches the rule at all.
+  # The rule's own comment says it may not be consulted before the ref check;
+  # this is the half of that contract the caller owes.
   if ! remote_ref_exists "$br"; then
     # No ref carries two meanings and this used to answer `open` for both: a
     # branch never started, and a branch merged with its ref deleted at merge.
@@ -3028,15 +3107,34 @@ branch_state() {
     # `merged` is already the state that settles a wave, so the arithmetic does
     # not change and no new state enters the vocabulary. Where no evidence
     # exists — squash merges, a hand-rewritten subject, a branch genuinely
-    # never started — today's `open` stands. The fix may only move a branch
-    # from `open` to `merged`, and only on positive evidence.
-    merged_by_subject "$br" && { echo "merged"; return; }
+    # never started — today's `open` stands. The evidence may only move a branch
+    # from `open` to `merged`, and only when it is positive.
+    merged_by_subject "$br" && _bs_subject=true
     # No merge commit names it — which is the ordinary case under a squash
     # merge, not an exotic one. The local walk is now out of evidence, so the
     # host is asked. It may only ever move this branch from `open` to `merged`:
-    # a miss, a CLOSED PR, or a host that cannot answer all fall through to the
-    # `open` below, exactly as before this call existed.
-    merged_by_host "$br" && { echo "merged"; return; }
+    # a miss, a CLOSED PR, or a host that cannot answer all leave the reading
+    # as it was, exactly as before this call existed.
+    #
+    # ASKED ONLY HERE, and that bound is the whole of PR #216: this arm is
+    # reached only for a branch with NO REF, so the per-branch host cost is
+    # bounded by ABSENT branches rather than by all of them. Hoisting the call
+    # out of this `if` to "gather uniformly" would put 22 round trips back into
+    # every scan on this repo. The reading is `-` for every branch that has a
+    # ref, and the rule never reaches its PR arm for one that does.
+    #
+    # THE TERMINAL CACHE WRAPS IT, and stays here rather than moving inward.
+    # The cache is about how OFTEN a question is asked; the rule is about what
+    # the answer MEANS. `merged_by_host` consults it, so a terminal branch is
+    # asked once and its answer is reused across pulses — 26 of 54 branches on
+    # this estate, measured 2026-08-19.
+    #
+    # THE WORD, NOT THE BOOLEAN. `merged_by_host` answers its own yes/no and
+    # leaves the state word it decided on in `_merged_by_host_state`, which is
+    # what travels: the rule tells `CLOSED` from `NONE` from `-`, and a boolean
+    # cannot. `|| true` because a not-merged answer is an ordinary reading and
+    # `set -e` must not read it as a failure.
+    merged_by_host "$br" || true
     # `open` IS A CLAIM ABOUT A PR: that one was looked for and none was found.
     # With no ref, the host is the only remaining source, so when it could not
     # be asked that claim was never earned — and the branch measured on
@@ -3064,11 +3162,14 @@ branch_state() {
     # `secondary` GATES LIKE THE OTHER TWO, and its faster recovery is no reason
     # to exempt it: the question was PUT and went unanswered, so this scan has
     # no more evidence than a throttled one does. What the two limits differ in
-    # is what to DO about it, which is the note below and not this branch.
-    case "$HOST_VERDICT" in
-      throttled|secondary|failed) echo "unknown"; return ;;
-    esac
-    echo "open"; return
+    # is what to DO about it, which is the note above and not this reading.
+    #
+    # THE THREE WORDS TRAVEL AS THEMSELVES. `HOST_VERDICT` is reported rather
+    # than collapsed into a boolean, so the rule keeps `unasked` apart from
+    # `failed` — the distinction the whole readings shape exists for.
+    printf '%s\t-\t%s\t%s\t%s\t%s\t0\t0' \
+      "$_bs_deferred" "$_bs_main" "$_bs_subject" "$HOST_VERDICT" "$_merged_by_host_state"
+    return
   fi
   # A CLAIM is a branch whose only commits beyond main are claim commits —
   # empty markers a dispatcher pushed to take the work. They must be real
@@ -3080,63 +3181,58 @@ branch_state() {
   # already computing and discarding, at one extra spawn per branch.
   local _bs_counts
   _bs_counts=$(real_commits_beyond_main "$br")
-  ahead=${_bs_counts%% *}
-  real=${_bs_counts##* }
-  if [ "${ahead:-0}" -gt 0 ]; then
-    [ "${real:-0}" = "0" ] && { echo "claimed"; return; }
-    # Real work that main does not yet contain: `wip`, and ONLY `wip`.
-    #
-    # This arm once asked `merge-base --is-ancestor origin/$br origin/$MAIN`
-    # here — "has the work already landed?" — and returned `merged` when it did.
-    # That question was already answered by the `ahead` count above it and could
-    # never fire: `ahead > 0` means `$br` carries at least one commit unreachable
-    # from `$MAIN`, and a branch with such a commit CANNOT be an ancestor of
-    # `$MAIN`, so `--is-ancestor` was false on every branch that reached it. It
-    # was one git spawn per `wip` branch spent to re-derive a fact already in
-    # hand — the per-branch tail this plan set out to thin — and its `merged`
-    # was dead code that changed no verdict.
-    #
-    # The landed-work case is not lost; it is answered ONE LEVEL UP. A branch
-    # whose commits are all in `$MAIN` counts `ahead = 0` and falls through to
-    # the `merged` below, and a merge that deleted the ref never reaches here at
-    # all (the no-ref arm returns first). If a future change makes `ahead`
-    # something other than "commits `$MAIN` lacks", THIS is the invariant that
-    # would break — the ancestry must move back, not be missed.
-    #
-    # A RESURRECTED REF BREAKS THE PREMISE ABOVE, and the join already knows.
-    # The reasoning "a merge that deleted the ref never reaches here" holds only
-    # while the ref STAYS deleted. `delete_branch_on_merge` is on, so the host
-    # removes it — and a worktree that still holds the branch can push it back
-    # afterwards, which a fleet does routinely. The ref then exists again while
-    # the work is on `$MAIN` under a DIFFERENT commit, because a squash merge
-    # rewrites it: `ahead > 0` (the pre-squash commits are unreachable from
-    # `$MAIN`), `real > 0` (they are real work), and this arm calls finished
-    # work `wip`.
-    #
-    # Measured 2026-08-23: `bug/done-holds-finished-plans-only`, PR #356 merged,
-    # read `wip` for three hours. Its wave reported "3 merged, the rest not yet"
-    # over four merged branches and never completed, so the plan sat in
-    # Development with nothing left to do.
-    #
-    # `wip` is the WORST of the wrong answers, which is why this earns a check
-    # rather than a note: it means *an agent is working here*, so a leftover
-    # worktree reads as an occupied desk and the row asks a reader to wait for
-    # something that finished.
-    #
-    # FREE, and that is what licenses it HERE. The state comes from the cache
-    # `prefill_pr_states` already filled from ONE repo-wide `pr-list`, so this
-    # adds no host call — asking per branch on this arm would put 22 calls back
-    # into every scan on this repo and undo the change that removed them. Where
-    # the list did not arrive the cache is empty, `host_pr_state` answers `-`,
-    # and the local walk decides exactly as it does today.
-    #
-    # ONLY `MERGED` MAY OVERRIDE the walk, and only toward `merged`. `OPEN`
-    # means a PR exists for work still in flight — which is what `wip` already
-    # says — and `CLOSED` or `NONE` are not evidence that anything landed.
-    if [ "$(host_pr_state "$br")" = MERGED ]; then echo "merged"; return; fi
-    echo "wip"; return
-  fi
-  # Nothing of its own. NOT a claim: that shape is indistinguishable from
+  _bs_ahead=${_bs_counts%% *}
+  _bs_real=${_bs_counts##* }
+  # Real work that main does not yet contain is `wip`, and ONLY `wip` — the
+  # rule says so; this reading is what lets it.
+  #
+  # This arm once asked `merge-base --is-ancestor origin/$br origin/$MAIN`
+  # here — "has the work already landed?" — and returned `merged` when it did.
+  # That question was already answered by the `ahead` count above it and could
+  # never fire: `ahead > 0` means `$br` carries at least one commit unreachable
+  # from `$MAIN`, and a branch with such a commit CANNOT be an ancestor of
+  # `$MAIN`, so `--is-ancestor` was false on every branch that reached it. It
+  # was one git spawn per `wip` branch spent to re-derive a fact already in
+  # hand — the per-branch tail this plan set out to thin — and its `merged`
+  # was dead code that changed no verdict.
+  #
+  # The landed-work case is not lost; it is answered by the TIP COMPARISON. A
+  # branch whose commits are all in `$MAIN` counts `ahead = 0`, and a merge that
+  # deleted the ref takes the no-ref arm above. If a future change makes `ahead`
+  # something other than "commits `$MAIN` lacks", THAT is the invariant that
+  # would break — the ancestry must move back, not be missed.
+  #
+  # A RESURRECTED REF BREAKS THE PREMISE ABOVE, and the host is what closes it.
+  # The reasoning "a merge that deleted the ref never reaches here" holds only
+  # while the ref STAYS deleted. `delete_branch_on_merge` is on, so the host
+  # removes it — and a worktree that still holds the branch can push it back
+  # afterwards, which a fleet does routinely. The ref then exists again while
+  # the work is on `$MAIN` under a DIFFERENT commit, because a squash merge
+  # rewrites it: `ahead > 0`, `real > 0`, and the walk alone would call finished
+  # work `wip`.
+  #
+  # Measured 2026-08-23: `bug/done-holds-finished-plans-only`, PR #356 merged,
+  # read `wip` for three hours. Its wave reported "3 merged, the rest not yet"
+  # over four merged branches and never completed, so the plan sat in
+  # Development with nothing left to do.
+  #
+  # `wip` is the WORST of the wrong answers, which is why this earns a reading
+  # rather than a note: it means *an agent is working here*, so a leftover
+  # worktree reads as an occupied desk and the row asks a reader to wait for
+  # something that finished.
+  #
+  # FREE, and that is what licenses reading it for EVERY branch with a ref. The
+  # state comes from the cache `prefill_pr_states` already filled from ONE
+  # repo-wide `pr-list`, so this adds no host call — no `--ask` here, which is
+  # what keeps the 22 round trips out. Where the list did not arrive the cache
+  # is empty, `host_pr_state` answers `-`, and the local walk decides exactly as
+  # it does today.
+  #
+  # ONLY `MERGED` MAY OVERRIDE the walk, and only toward `merged` — the rule's
+  # business, not this function's. `OPEN` means a PR exists for work still in
+  # flight, and `CLOSED` or `NONE` are not evidence that anything landed.
+  #
+  # Nothing of its own is NOT a claim: that shape is indistinguishable from
   # merged work, which is exactly why claims carry a commit.
   #
   # ZERO AHEAD CARRIES TWO SHAPES, and only one of them is landed work:
@@ -3147,7 +3243,7 @@ branch_state() {
   #   | reset to main  | is an ancestor → merged | holds nothing |
   #
   # A branch pointing AT the default branch is trivially an ancestor of it, so
-  # every ancestry test passes — right for the case this arm was built for (a
+  # every ancestry test passes — right for the case that arm was built for (a
   # squash merge leaves the branch behind, and its work IS on main), and wrong
   # for a branch that was reset, where the same shape means it holds NOTHING.
   #
@@ -3159,33 +3255,41 @@ branch_state() {
   # this error does not stall the fleet — it advances it onto a seam nobody
   # wrote, which is the worse direction.
   #
-  # THE DISCRIMINATOR IS THE OTHER DIRECTION. A branch with zero commits ahead
+  # THE DISCRIMINATOR IS THE OTHER DIRECTION, and it is why BOTH TIPS are
+  # reported rather than a verdict about them. A branch with zero commits ahead
   # is either equal to the default branch or a strict ancestor of it, so
   # "behind = 0" and "tip = main tip" are the same predicate. Compared as OIDs
   # because BOTH ARE ALREADY IN HAND from the ref batch — a `rev-list --count`
   # would re-derive it at one spawn per branch, the per-branch tail this scan
   # has repeatedly been thinned to remove.
   #
-  # OFFLINE, AND DELIBERATELY SO. No host call is added here:
+  # OFFLINE, AND DELIBERATELY SO. No `--ask` is added here:
   # `a-throttled-host-says-so` measured `plot-pr-merged.sh` answering *not
   # merged* for three genuinely merged branches while throttled, and this
   # reading must not inherit that failure mode.
   #
   # The squash path is untouched and must stay so — its mirror defect (a
   # squash-merged branch reading `open`) is a separate plan, and a fix for one
-  # can break the other. A squash-merged branch is BEHIND main and reaches the
-  # `merged` below; a squash-merged branch whose ref was pushed back counts
-  # `ahead > 0` and never arrives here at all.
-  local _bs_tip _bs_main
+  # can break the other. A squash-merged branch is BEHIND main and its tips
+  # differ; a squash-merged branch whose ref was pushed back counts `ahead > 0`.
   _bs_tip=$(remote_ref_oid "$br")
-  _bs_main=$(remote_ref_oid "$MAIN")
-  if [ -n "$_bs_tip" ] && [ "$_bs_tip" = "$_bs_main" ]; then
-    # It points AT the default branch: no work of its own, and none of its own
-    # landed. `open` is what this scan already says for work not yet done, so
-    # no new state enters the vocabulary and the wave arithmetic is unchanged.
-    echo "open"; return
-  fi
-  echo "merged"
+  [ -n "$_bs_tip" ] || _bs_tip="-"
+  printf '%s\t%s\t%s\tfalse\t%s\t%s\t%s\t%s' \
+    "$_bs_deferred" "$_bs_tip" "$_bs_main" "$HOST_VERDICT" "$(host_pr_state "$br")" \
+    "${_bs_ahead:-0}" "${_bs_real:-0}"
+}
+
+# THE RULE, ASKED ONCE PER PLAN. `branchState` lives in `@plot-pm/domain` and
+# this is how the scan reaches it: readings in, one `state<TAB>needs` line per
+# branch out, in the order they were given.
+#
+# A MISSING OR SILENT ARTIFACT REFUSES, exactly as the verdicts call does.
+# There is no shell fallback: a second implementation kept "just in case" is
+# the duplication this adoption removes, and it would be the copy nobody tests.
+# `plot-deliver.sh` fails the same way for the same reason.
+ask_branch_states() { # stdin=readings → one `state<TAB>needs` line per branch
+  node "$script_dir/board/plot-branch-state.mjs" 2>/dev/null \
+    || { echo "error: cannot read branch states — run 'pnpm build:board'." >&2; exit 2; }
 }
 
 # Prose is suppressed by BOTH alternate output modes. --json accumulates the
@@ -3402,36 +3506,112 @@ for plan in "${plans[@]}"; do
   # between `why` and the wave name, which moved the wave name to field 7: the
   # `awk` that reads it below was updated with this line and the two must move
   # together.
-  states=""
+  # PASS 1a: THE READINGS. Every branch of this plan, gathered and not judged.
+  #
+  # `branch_readings` is the git archaeology that used to end in an `if` chain.
+  # It now ends in eight tab-separated readings, and the two the plan states —
+  # the prerequisite's name and what the host said about it — are appended here.
+  #
+  # THE PREREQUISITE'S PR STATE IS NOT READ YET, and `?` says so. `-` is taken:
+  # `host_pr_state` answers it for a host that could not be reached, and the
+  # rule reads that as `unreadable` and answers `waiting`, because silence is
+  # not evidence in either direction. The two were one marker until CI ran the
+  # corpus with no token, where every prerequisite answers `-` and every waiting
+  # branch read `open`. Reading it
+  # costs a host round trip (`waits_pr_state` passes `--ask`, because a delivered
+  # prerequisite's ref is gone and only its PR outlives it), and the scan spends
+  # that only where the answer could change the branch's state. Which states
+  # those are IS the precedence, so the rule reports it rather than this loop
+  # deciding it — see pass 1c.
+  readings=""
+  order=""
   while IFS=$'\t' read -r idx br deferred why waits wname claim; do
     [ -n "$br" ] || continue
     # "-" is the absent marker the shim writes, for the tab-collapse reason
     # above. Normalized here so everything downstream tests emptiness.
     [ "$waits" = "-" ] && waits=""
-    if [ "$deferred" = "true" ]; then st="deferred"; else st=$(branch_state "$br"); fi
-    # THE PREREQUISITE, AFTER THE BRANCH'S OWN STATE AND ONLY OVER TWO OF ITS
-    # WORDS. `deferred` outranks it — somebody gave the branch up, which is a
-    # decision, while waiting is a measurement — and so does any state that
-    # means work exists: `wip`, `claimed` and `merged` all say the branch was
-    # started, and overriding `merged` would stop its wave settling FOREVER,
-    # which is the blocked-on-success failure this feature is built to avoid.
-    #
-    # So the override lands exactly where the defect was: a branch that reads
-    # as unstarted, which is the population `--next` hands out.
-    if [ -n "$waits" ]; then
-      case "$st" in
-        open|unknown)
-          waits_st=$(waits_state "$waits")
-          [ -n "$waits_st" ] && st="$waits_st" ;;
-      esac
-    fi
-    # "-" GOES BACK IN, for the reason it was there in the first place: this
-    # record is re-read by two more `read` loops below, and an EMPTY middle
-    # column collapses its tab into its neighbour's and shifts every later
-    # field left. `$claim` is the only field allowed to be last and optional.
-    states+="$idx	$br	$st	$deferred	$why	${waits:--}	$wname	$claim"$'\n'
+    readings+="$(branch_readings "$br" "$deferred")	${waits:--}	?"$'\n'
+    order+="$idx	$br	$deferred	$why	${waits:--}	$wname	$claim"$'\n'
   done <<< "$wave_lines"
 
+  # PASS 1b: THE DECISION, and it is not made here.
+  #
+  # `branchState` lives in `@plot-pm/domain` and this script asks it. The eight
+  # words and the precedence that merges them — a plan's `deferred:` over
+  # everything git says, the ref check before the merge lookup, a prerequisite
+  # over `open` and `unknown` and nothing else — are one implementation now,
+  # with a test per case, shared with every component that has to agree about
+  # what a branch is.
+  #
+  # ONE CALL PER PLAN, not per branch, for the reason pass 2b gives: the board
+  # polls this scan every five seconds against ~40 plans, and a process per
+  # branch is the per-branch tail this script has repeatedly been thinned to
+  # remove.
+  #
+  # A MISSING OR SILENT ARTIFACT REFUSES, exactly as the verdicts call does.
+  # There is no shell fallback: a second implementation kept "just in case" is
+  # the duplication this adoption removes, and it would be the copy nobody
+  # tests.
+  branch_answers=$(printf '%s' "$readings" | ask_branch_states)
+  [ "$(printf '%s\n' "$branch_answers" | grep -c .)" = "$(printf '%s' "$readings" | grep -c .)" ] \
+    || { echo "error: branch states did not answer for every branch of $plan_base." >&2; exit 2; }
+
+  # PASS 1c: THE PREREQUISITES THE RULE ASKED FOR, and only those.
+  #
+  # The second column of each answer is the rule's own
+  # `REPLACEABLE_BY_PREREQUISITE` — `1` where this branch names a prerequisite
+  # whose state has not been read and where reading it could change the answer.
+  # `deferred` outranks it, and so does any state meaning work exists: `wip`,
+  # `claimed` and `merged` all say the branch was started, and overriding
+  # `merged` would stop its wave settling FOREVER. That reasoning now sits in
+  # `branch-state.ts` with a test per case; this loop only spends the calls it
+  # is told to.
+  #
+  # SO THE SECOND ASK IS PAID ONLY WHEN SOMETHING IS FLAGGED, and the bound is
+  # the flagged branches rather than the annotated ones: a `waits:` branch that
+  # already reads `wip`, `claimed`, `merged` or `deferred` costs nothing.
+  refill=""
+  needs_refill=0
+  answer_i=0
+  while IFS= read -r rd_line; do
+    [ -n "$rd_line" ] || continue
+    answer_i=$((answer_i + 1))
+    IFS=$'\t' read -r _st needs \
+      <<< "$(printf '%s\n' "$branch_answers" | sed -n "${answer_i}p")"
+    waits_br=$(printf '%s' "$rd_line" | cut -f9)
+    if [ "$needs" = "1" ] && [ "$waits_br" != "-" ]; then
+      needs_refill=1
+      # `--ask` because the prerequisite is precisely the branch the repo-wide
+      # list may legitimately omit: its plan may be delivered and its ref gone.
+      # `host_pr_state`'s run cache keeps this at one call per prerequisite per
+      # run, never one per pass.
+      refill+="$(printf '%s' "$rd_line" | cut -f1-9)	$(waits_pr_state "$waits_br")"$'\n'
+    else
+      refill+="$rd_line"$'\n'
+    fi
+  done <<< "$readings"
+
+  if [ "$needs_refill" = 1 ]; then
+    branch_answers=$(printf '%s' "$refill" | ask_branch_states)
+    [ "$(printf '%s\n' "$branch_answers" | grep -c .)" = "$(printf '%s' "$refill" | grep -c .)" ] \
+      || { echo "error: branch states did not answer for every branch of $plan_base." >&2; exit 2; }
+  fi
+
+  # PASS 1d: the record every loop below reads, with the decided state in it.
+  #
+  # "-" GOES BACK IN, for the reason it was there in the first place: this
+  # record is re-read by two more `read` loops below, and an EMPTY middle
+  # column collapses its tab into its neighbour's and shifts every later
+  # field left. `$claim` is the only field allowed to be last and optional.
+  states=""
+  answer_i=0
+  while IFS=$'\t' read -r idx br deferred why waits wname claim; do
+    [ -n "$br" ] || continue
+    answer_i=$((answer_i + 1))
+    st=$(printf '%s\n' "$branch_answers" | sed -n "${answer_i}p" | cut -f1)
+    states+="$idx	$br	$st	$deferred	$why	$waits	$wname	$claim"$'\n'
+  done <<< "$order"
+
   # Pass 2a: what each wave HOLDS — how many of its non-deferred branches have
   # not settled. A reading, and the whole of what this script contributes to the
   # verdict: which branches count as settled depends on `--loose` and on a host
@@ -3573,7 +3753,7 @@ for plan in "${plans[@]}"; do
         claimable+=("$br")
       fi
       [ "$quiet" = 1 ] || echo "      $br — $note"
-      if [ "$as_json" = 1 ]; then
+      if [ "$build_doc" = 1 ]; then
         # The INTERNAL state ($st), never the prose label ($note): the board
         # must not parse a string that exists for humans to read.
         json_branches+="${json_branches:+,}{\"branch\":\"$(json_str "$br")\""
@@ -3771,7 +3951,7 @@ for plan in "${plans[@]}"; do
       fi
     done <<< "$states"
 
-    if [ "$as_json" = 1 ]; then
+    if [ "$build_doc" = 1 ]; then
       json_waves+="${json_waves:+,}{\"name\":\"$(json_str "$wname")\""
       json_waves+=",\"verdict\":\"$verdict\",\"branches\":[$json_branches]}"
     fi
@@ -3785,7 +3965,7 @@ for plan in "${plans[@]}"; do
     # what the wave before it decided.
     [ "$verdict" = "blocked" ] && n_blocked=$((n_blocked + 1))
   done
-  if [ "$as_json" = 1 ]; then
+  if [ "$build_doc" = 1 ]; then
     # ONE composition, two destinations — the property that makes --stream and
     # --json say the same thing rather than agreeing by inspection. A second
     # `printf` shaped like this one would be a second implementation of the
@@ -3883,28 +4063,123 @@ if [ "$log_pulse" = 1 ]; then
   done
 fi
 
-# --json: the same derivation as the prose above, rendered for machines. It is
-# an OUTPUT MODE and nothing more — it composes with --offline/--no-fetch/
-# --loose rather than implying any of them, so the board's data depends on what
-# it asked for, not on how it asked. --next wins over it (handled above): that
-# is a different question with a one-line answer.
-if [ "$as_json" = 1 ]; then
-  # --stream wraps the SAME document in one tagged line rather than emitting a
-  # second, smaller one. The terminal object is what proves the scan finished:
-  # a consumer that has seen `plan` lines and no `reading` line has a PARTIAL
-  # answer and must say so — which is the whole distinction this mode adds, and
-  # the reason the end is marked rather than inferred from the pipe closing.
-  # A killed scan closes the pipe too.
-  [ "$stream" = 1 ] && printf '{"kind":"reading","reading":'
+# THE PULSE RECORDS ITSELF — `.plot/state/last-pulse.json`, the bridge.
+#
+# WHY THE SCAN AND NOT THE BOARD. `fleet.ts:2804` was the ONLY writer until
+# 2026-09-06, and this script named the file zero times — so `/plot-pulse` in a
+# repository with no board had nothing to diff against, and every pulse was a
+# first one forever. `DESIGN-process.md` §1 requires the fleet to work with no
+# board at all. The scan produces the pulse; the component that produces one
+# records it. The board's write is not removed and becomes redundant: the board
+# spawns THIS script, so a scan that writes the bridge writes it on the board's
+# path too, from inside the same run.
+#
+# INSIDE THE SUCCESS PATH, WHICH IS THE PROPERTY THAT HAD TO SURVIVE THE MOVE.
+# `fleet.ts:2800`: *"A scan that failed must not overwrite the last good answer
+# — the only thing standing between a `--watch` restart and an empty board."*
+# So this is called where the scan has finished deriving and is about to say so,
+# never from a trap and never at exit. A killed scan leaves the previous file
+# whole.
+#
+# THE FORMAT IS `pulse-bridge.ts`'s AND EVERY FIELD HERE IS ITS REQUIREMENT.
+# `version` must equal `BRIDGE_VERSION` or `:193` returns null and the board
+# renders an empty page with no error — a silent failure, which is why the
+# board's own test reads a file this script wrote rather than one a fixture
+# invented. `at` is epoch MILLISECONDS and is checked against
+# `BRIDGE_MAX_AGE_MS` (15 min), and a file from the future is rejected outright
+# rather than clamped, so the clock must be the same one the board reads.
+#
+# THE FOUR MAPS ARE EMPTY AND THAT IS HONEST. `ages`, `approvedAt` and
+# `ideaPlans` are computed by the board on its own timers, and `branchUrlBase`
+# comes from its settings; the scan knows none of them. `readBridge` rebuilds
+# each with `toMap`, which yields an empty Map for anything it cannot use, and
+# `branchUrlBase` falls back to `''`. So a scan-written bridge serves the rows,
+# the verdicts and the counts, with unknown ages and no branch links — degraded
+# in the direction the board already handles, and overwritten by the board's own
+# richer write seconds later on the refresh it always issues.
+#
+# TEMP FILE PLUS RENAME, carrying the pid, exactly as `writeBridge` does and for
+# the same reason: `rename` is atomic within a filesystem, so a board reading
+# while this writes sees the old file whole or the new file whole. The pid is in
+# the temp name because two scans on one repo — routine here — must not collide
+# on one temp file and hand the reader the torn payload the rename exists to
+# prevent.
+#
+# EVERY FAILURE IS SWALLOWED, the rule `writeBridge` states: a read-only
+# checkout, a full disk, a `.plot` nobody may write to. None of that is a reason
+# for a pulse to fail, and the cost of the miss is exactly the behaviour before
+# this existed.
+#
+# IT IS A CACHE WITH AN EXPIRY, NEVER A RECORD. Deleting it changes no
+# behaviour, because the next pulse re-derives everything — which is what keeps
+# this inside the script's stateless design rather than beside it.
+# The previous pulse's document, read BEFORE `write_bridge` replaces it.
+#
+# EMPTY MEANS NO FILE, and that is a fact about the FILE rather than about its
+# contents — it is what separates a first run from a history that exists and
+# cannot be used. A file that is present but truncated, or written in a shape
+# this build does not know, arrives here as its own bytes and the renderer
+# decides; a file that was never there arrives as "".
+#
+# READ ONCE, EARLY, because `write_bridge` overwrites it on the success path and
+# the delta compares against what was there when this scan started.
+PREVIOUS_PULSE=""
+read_previous_pulse() {
+  local root file
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || return 0
+  [ -n "$root" ] || return 0
+  file="$root/.plot/state/last-pulse.json"
+  [ -f "$file" ] || return 0
+  # A HUGE OR UNREADABLE FILE COSTS THE DELTA, NEVER THE PULSE. Every failure
+  # here leaves PREVIOUS_PULSE empty, which reads as a first run — the same
+  # answer the scan gave before this existed.
+  PREVIOUS_PULSE=$(cat "$file" 2>/dev/null | tr -d '\n') || PREVIOUS_PULSE=""
+  return 0
+}
+
+write_bridge() {
+  [ "$record" = 1 ] || return 0
+  [ -n "$reading_doc" ] || return 0
+  # The bridge belongs to the REPOSITORY, not to the directory the scan was run
+  # from. Every other path here is relative to the cwd because the board spawns
+  # this from the root; the board reads the bridge at `repoRoot`, so this asks
+  # git rather than assuming the two agree.
+  local root file tmp
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || return 0
+  [ -n "$root" ] || return 0
+  file="$root/.plot/state/last-pulse.json"
+  mkdir -p "$root/.plot/state" 2>/dev/null || return 0
+  tmp="$file.$$.tmp"
+  # `at` is when the scan COMPLETED, which is what `pulse-bridge.ts:81` asks for
+  # — "NOT when it was written" — and the two are the same instant here.
+  printf '{"version":1,"at":%s,"pulse":%s,"ages":[],"branchUrlBase":"","approvedAt":[],"ideaPlans":[]}' \
+    "$(( $(date +%s) * 1000 ))" "$reading_doc" > "$tmp" 2>/dev/null || {
+      rm -f "$tmp" 2>/dev/null
+      return 0
+    }
+  mv -f "$tmp" "$file" 2>/dev/null || rm -f "$tmp" 2>/dev/null
+  return 0
+}
+
+# THE READING, COMPOSED ONCE. Two consumers read it — `--json`/`--stream` print
+# it, and `write_bridge` records it — and composing it twice is how the printed
+# document and the recorded one start to disagree. Assembled only when
+# `build_doc` is on, because the branch objects inside `$json_plans` cost
+# `merge-tree` per unlanded branch.
+if [ "$build_doc" = 1 ]; then
+  # BEFORE THE DOCUMENT IS COMPOSED AND LONG BEFORE IT IS WRITTEN. The delta
+  # compares against the pulse that was on disk when this scan started, and
+  # `write_bridge` replaces that file on the success path below.
+  read_previous_pulse
   # `read_ref` is the ref this document was derived from; `local_head` is the
   # checkout it was derived ON. A consumer needs both to tell "the board is
   # current" from "the board is current about an old world".
   #
   # `head` repeats `local_head` as an alias for one release. The board reads it
   # today; it goes away once the board reads the pair.
-  printf '{"main":"%s","read_ref":"%s","local_head":"%s","head":"%s",' \
+  reading_doc=$(printf '{"main":"%s","read_ref":"%s","local_head":"%s","head":"%s",' \
     "$(json_str "$MAIN")" "$(json_str "$READ_REF")" "$(json_str "$LOCAL_HEAD")" \
-    "$(json_str "$HEAD_SHORT")"
+    "$(json_str "$HEAD_SHORT")")
   # Three more facts about the EVIDENCE, not about the fleet — a consumer that
   # renders the numbers below should be able to say how much to trust them.
   # They answer the question `read_ref` raises: that field names the ref, and
@@ -3913,11 +4188,11 @@ if [ "$as_json" = 1 ]; then
   # `fetch_failed` used to be discarded by `2>/dev/null`, so refs an hour old
   # were reported with the confidence of refs a second old. `plan_source` says
   # whether the plan list came from the ref or fell back to this checkout.
-  printf '"fetch_failed":%s,"fetch_error":"%s","plan_source":"%s","plans":[%s],' \
+  reading_doc+=$(printf '"fetch_failed":%s,"fetch_error":"%s","plan_source":"%s","plans":[%s],' \
     "$([ "$FETCH_FAILED" = 1 ] && echo true || echo false)" \
-    "$(json_str "$FETCH_ERROR")" "$(json_str "$PLAN_SOURCE")" "$json_plans"
-  printf '"summary":{"plans":%d,"waves":%d,"branches":%d,"claimed":%d,' \
-    "$n_plans" "$n_waves" "$n_branches" "$n_claimed"
+    "$(json_str "$FETCH_ERROR")" "$(json_str "$PLAN_SOURCE")" "$json_plans")
+  reading_doc+=$(printf '"summary":{"plans":%d,"waves":%d,"branches":%d,"claimed":%d,' \
+    "$n_plans" "$n_waves" "$n_branches" "$n_claimed")
   # `host` is the EVIDENCE field beside merge_detect, and it is the one that
   # says whether merge_detect can be believed. Rendered for the machine here
   # and in the footer for a human; the board reads this rather than parsing
@@ -3926,9 +4201,29 @@ if [ "$as_json" = 1 ]; then
   # WAVES. Two vocabularies share the word `blocked` and the footer must not:
   # a consumer adding the three would double-count nothing, because no branch
   # is in both and no wave is in either.
-  printf '"eligible":%d,"blocked":%d,"deferred":%d,"waiting":%d,"prereq_missing":%d,"merge_detect":"%s","host":"%s"}}' \
+  reading_doc+=$(printf '"eligible":%d,"blocked":%d,"deferred":%d,"waiting":%d,"prereq_missing":%d,"merge_detect":"%s","host":"%s"}}' \
     "$n_eligible" "$n_blocked" "$n_deferred" "$n_waiting" "$n_prereq_missing" \
-    "$MERGE_DETECT" "$HOST_VERDICT"
+    "$MERGE_DETECT" "$HOST_VERDICT")
+fi
+
+# --json: the same derivation as the prose above, rendered for machines. It is
+# an OUTPUT MODE and nothing more — it composes with --offline/--no-fetch/
+# --loose rather than implying any of them, so the board's data depends on what
+# it asked for, not on how it asked. --next wins over it (handled above): that
+# is a different question with a one-line answer.
+if [ "$as_json" = 1 ]; then
+  # THE SCAN COMPLETED, so the bridge may be replaced. Before the document is
+  # printed rather than after: a consumer that reads the terminal line and then
+  # kills us must still find the file written.
+  write_bridge
+  # --stream wraps the SAME document in one tagged line rather than emitting a
+  # second, smaller one. The terminal object is what proves the scan finished:
+  # a consumer that has seen `plan` lines and no `reading` line has a PARTIAL
+  # answer and must say so — which is the whole distinction this mode adds, and
+  # the reason the end is marked rather than inferred from the pipe closing.
+  # A killed scan closes the pipe too.
+  [ "$stream" = 1 ] && printf '{"kind":"reading","reading":'
+  printf '%s' "$reading_doc"
   [ "$stream" = 1 ] && printf '}'
   printf '\n'
   exit 0
@@ -4004,5 +4299,33 @@ if [ "$PLAN_SOURCE" != "ref" ]; then
   echo "  note: origin/$MAIN could not be read — plans were listed from this"
   echo "        checkout instead, so the list is only as current as your last pull."
 fi
+# THE PROSE PATH'S TERMINAL POINT, and the counterpart to the `--json` write
+# above. `/plot-pulse` runs this path — it passes `--log-pulse` and no `--json`
+# — so without a write here the boardless repository the plan names would still
+# accumulate no history. A no-op unless `--log-pulse` turned assembly on.
+#
+# Below every `note:` the report emits and above the sentence that says the scan
+# finished: a scan killed while printing its notes has not completed, and must
+# not replace the last good answer.
+# WHAT CHANGED SINCE THE LAST PULSE, above the line that says this one
+# finished. The rule is `pulseDelta` in the domain and this prints what it
+# decided — no comparison happens here, and one written here would be the
+# second implementation of a rule that already has tests.
+#
+# ONLY WHERE A PULSE WAS PRODUCED FOR SOMEBODY TO READ. `build_doc` is what says
+# the reading was assembled at all, and `record` is what says this run is one of
+# the two that produce a pulse rather than answer a query. A `--next` caller
+# asking what to work on is told nothing new.
+#
+# EVERY FAILURE IS SILENT AND COSTS ONLY THE DELTA. A missing artifact, an
+# unreadable previous pulse, a node that will not start — the full report below
+# is exactly what it was before this existed, which is the degradation this
+# whole line is optional against.
+if [ "$build_doc" = 1 ] && [ "$record" = 1 ] && [ -n "$reading_doc" ]; then
+  delta_out=$(printf '%s\n%s\n' "$PREVIOUS_PULSE" "$reading_doc" \
+    | node "$script_dir/board/plot-delta.mjs" 2>/dev/null) || delta_out=""
+  [ -n "$delta_out" ] && { printf '%s\n' "$delta_out"; echo; }
+fi
+write_bridge
 echo "Pulse complete. This report is derived — nothing was changed."
 echo "summary: plans=$n_plans waves=$n_waves branches=$n_branches claimed=$n_claimed eligible=$n_eligible blocked=$n_blocked deferred=$n_deferred waiting=$n_waiting prereq_missing=$n_prereq_missing merge_detect=$MERGE_DETECT host=$HOST_VERDICT main=$MAIN"