@plot-pm/board 0.9.1 → 0.11.0

package/plot-dispatch.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Plot helper: fan out one worktree + one worker per eligible branch.
+# Plot helper: hand one slice + its brief to the registry per eligible branch.
 # Usage: plot-dispatch.sh [--dry-run] [--no-start] [--no-brief] [--offline]
 #                         [--max N] [--allow-local] <slug>
 #        plot-dispatch.sh --migrate [--yes] [--max N]
@@ -22,29 +22,42 @@
 #               config — without one there is no destination. --dry-run by
 #               default; --yes to actually move.
 #   --dry-run   print what would happen; create nothing, push nothing
+#   --monitors  with --dry-run, also name which monitors would be attached to
+#               which worktree. Opt-in so the default --dry-run output stays
+#               byte-identical, which is what lets it be diffed against a run
+#               from before a change to this script.
 #   --yes       with --migrate, actually move the worktrees (default is dry-run)
-#   --no-start  create worktrees and claim refs, but start no workers
-#   --no-brief  start a worker even when its branch has no brief. The named
-#               escape for the brief gate: a missing brief PREPARES (worktree +
-#               claim) but does not START, because the worker's first
-#               instruction is to read `.plot/briefs/<branch>.md` and it has
-#               nothing to read. --no-brief overrides that and says so.
+#   --no-start  record that no worker was wanted: the run still hands its slices
+#               over, and reports `worker=suppressed` rather than a missing
+#               `Worker command`. Dispatch starts no worker either way — the
+#               registry spawns agents — so this now says WHY the zero was
+#               chosen and no longer changes what the run does.
+#   --no-brief  hand a slice over even when its branch has no brief. The named
+#               escape for the brief gate: a missing brief is not handed over,
+#               because the agent's first instruction is to read
+#               `.plot/briefs/<branch>.md` and it has nothing to read. A refused
+#               slice leaves no desk and no claim and stays in the queue.
+#               --no-brief overrides that and says so.
 #   --offline   skip `git fetch`
 #   --max N     dispatch at most N branches this run (default: all eligible)
 #   --allow-local  read the plan's phase from the working tree when
 #               origin/<main> cannot be resolved (no remote, fresh clone).
 #               The explicit escape for a remote-less repo — never a default,
 #               because a working-tree read is what this gate exists to avoid.
+#   --allow-waiting  dispatch a branch whose `waits:` prerequisite has not
+#               merged. The named escape for the prerequisite gate, in the
+#               tradition of --allow-local: a gate with no exit is one people
+#               route around by never annotating at all. It says so on the
+#               line it overrides, so the override is on the record.
 #   <slug>      the plan to fan out
 # Output: one line per branch, each optionally followed by an indented
 #         `in flight:` line naming a branch that already holds files, then the
-#         summary block — an optional prose consequence line, then a
 #         machine-countable footer.
 #         A branch whose worktree exists with UNMERGED work is refused rather
-#         than dispatched — counted `skipped`, with the worktree path named,
+#         than handed over — counted `skipped`, with the worktree path named,
 #         in `--dry-run` identically to a real run. See "THE HELD-BRANCH GATE".
-#             3 worktrees prepared, 0 workers started, no `Worker command` configured
-#             summary: dispatched=2 reused=0 skipped=1 started=2 brief=missing worker=unconfigured
+#             handed over feature/one → the registry
+#             summary: dispatched=2 reused=0 skipped=1 started=0 brief=missing worker=unconfigured brief_asked=0
 #
 # THE CONSEQUENCE IS STATED IN THE SUMMARY, NOT PER BRANCH. start_worker has
 # always said "no 'Worker command' configured" beside the branch it could not
@@ -77,6 +90,23 @@
 # over. It does NOT refuse: --dry-run and --status are legitimate direct calls,
 # and a gate that blocks looking-before-leaping is a gate in the wrong place.
 #
+# `brief_asked=N` counts what the script did about it, and the distinction from
+# `brief=missing` is exact: this script still writes no brief, it ASKS one to be
+# written. `Brief command` names how to run an agent headless for one prompt,
+# and the prompt is `/plot-implement <slug>` — the skill that already owns brief
+# authorship. Absent key, or `none`: nothing is asked, the branch is refused as
+# before, and the per-branch line names `no-brief-command` so the log says which
+# arm ran. A project that never sets the key sees `brief_asked=0` and today's
+# behaviour exactly.
+#
+# `brief_asked=N` COUNTS COMMANDS STARTED, NEVER BRIEFS WRITTEN. The command is
+# detached by design and this script never waits on it, so a command that dies
+# in its first millisecond is counted the same as one that writes and pushes a
+# brief. Measured 2026-09-02: a `Brief command` that could not reach
+# `/plot-implement` wrote a 33-byte log and the summary reported
+# `brief_asked=1`. The per-branch line names the log for exactly this reason —
+# the log is the evidence, the count is only that an attempt was made.
+#
 # THIS IS THE ONE SCRIPT IN THE FLEET THAT WRITES. Everything else
 # (plot-fleet-scan.sh, plot-reconcile-scan.sh) is read-only. Consequently every
 # write here is either idempotent or refused:
@@ -113,6 +143,14 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck source=plot-worker-state.sh
 . "$script_dir/plot-worker-state.sh"
 
+# The ONE answer to "did the host merge ANY PR for this branch?" — `pr_merged`,
+# read by `held_worktree` rather than derived from ancestry. Sourced for the
+# same reason `plot-reap.sh` and `plot-release-refs.sh` source it: three callers
+# gate on one fact and must never disagree about it. The helper defines two
+# functions and does nothing else on load.
+# shellcheck source=plot-pr-merged.sh
+. "$script_dir/plot-pr-merged.sh"
+
 # ---------------------------------------------------------------------------
 # WHERE THE WORKTREES LIVE, and by what name
 # ---------------------------------------------------------------------------
@@ -155,6 +193,7 @@ resolve_wt_root() { # $1=repo_root → sets globals wt_root, wt_prefix
 }
 
 dry_run=0
+show_monitors=0
 no_start=0
 no_brief=0
 mode=dispatch
@@ -162,12 +201,23 @@ stop_branch=""
 restart_branch=""
 offline=""
 allow_local=0
+allow_waiting=0
 max=0
 slug=""
 migrate_yes=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --dry-run)  dry_run=1 ;;
+    # --monitors NAMES what would be attached, and it is OPT-IN for a reason
+    # that is a protection rather than a preference. `plot-dispatch.sh` is the
+    # largest script here and a mistake in start_worker starts no workers at
+    # all, so this slice pins `--dry-run` output as BYTE-IDENTICAL before and
+    # after on the same estate — the dry run exercises every refusal against
+    # real worktrees and real pids without starting or removing anything, which
+    # is the same protection the reap and dispatch domain work used. A line
+    # added to the default output would forfeit exactly that check. So the
+    # naming lives behind its own flag: `--dry-run --monitors`.
+    --monitors) show_monitors=1 ;;
     --status)   mode=status ;;
     --migrate)  mode=migrate ;;
     --yes)      migrate_yes=1 ;;
@@ -184,12 +234,13 @@ while [ $# -gt 0 ]; do
     --no-brief) no_brief=1 ;;
     --offline|--no-fetch) offline="--offline" ;;
     --allow-local) allow_local=1 ;;
+    --allow-waiting) allow_waiting=1 ;;
     --max)      max="${2:?--max needs a value}"
                 case "$max" in
                   ''|*[!0-9]*) echo "plot-dispatch: --max needs a number, got '$max'" >&2; exit 1 ;;
                 esac
                 shift ;;
-    -h|--help)  sed -n '2,38p' "$0"; exit 0 ;;
+    -h|--help)  sed -n '2,46p' "$0"; exit 0 ;;
     *)          slug="$1" ;;
   esac
   shift
@@ -248,6 +299,22 @@ json_escape() {
 #
 # Model and context are still absent on purpose: they belong to the runtime and
 # are read from the transcript, so a manifest that named them would be a guess.
+#
+# `resumeId` AND `session` ARE TWO FIELDS THAT HOLD ONE VALUE AT LAUNCH, and
+# they are written separately on purpose. `session` is the transcript join key
+# and STAYS FIXED across a branch hop, by design — `plot-worker-loop.sh` rewrites
+# `branch` and `worktree` on each hop and leaves `session` alone. The resume
+# handle is a different identity with a different lifetime, and whether it should
+# follow a hop cannot even be ASKED while one field carries both meanings. They
+# will usually agree; nothing may assume they always do.
+#
+# `attempts` IS THE SUPERVISOR'S OWN COUNTER, DISTINCT FROM `relaunches`.
+# `relaunches` counts operator-initiated restarts — a human's record, written by
+# the launch stamp. `attempts` counts a supervisor's own retries and is what a
+# bound would read. Merging them would let a person's three manual restarts
+# exhaust an automatic budget, or the reverse. It is written 0 here and by
+# nothing else in this script: no component in Plot raises it yet, and a launch
+# that guessed at one would be recording a retry nobody made.
 # The `pid` starts EMPTY here and is stamped by the wrapper the instant it learns
 # its own child — see `stamp_manifest_pid`. The dispatcher does not know the
 # agent pid at this line (only the wrapper does, from its `$!`), so it writes the
@@ -260,10 +327,12 @@ write_agent_manifest() { # $1=path $2=session $3=branch $4=worktree $5=command
   {
     printf '{\n'
     printf '  "session": "%s",\n' "$(json_escape "$2")"
+    printf '  "resumeId": "%s",\n' "$(json_escape "$2")"
     printf '  "branch": "%s",\n' "$(json_escape "$3")"
     printf '  "worktree": "%s",\n' "$(json_escape "$4")"
     printf '  "command": "%s",\n' "$(json_escape "$5")"
     printf '  "pid": "",\n'
+    printf '  "attempts": 0,\n'
     printf '  "startedAt": "%s"\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
     printf '}\n'
   } > "$tmp" 2>/dev/null || { rm -f "$tmp"; return 1; }
@@ -302,11 +371,16 @@ write_agent_manifest() { # $1=path $2=session $3=branch $4=worktree $5=command
 #
 # READ FROM `origin/<main>`, NOT THE WORKING TREE, for the same reason the phase
 # gate above does: the question is not "does a brief exist in this filesystem?"
-# but "will the WORKER find one?". The worker's worktree is created from
-# `origin/$MAIN` (see `git worktree add` below), so a brief committed nowhere —
-# or committed locally and never pushed — is invisible to it. Checking the
-# working tree passes the gate and starts a worker into an empty specification,
-# which is the exact failure this gate exists to prevent.
+# but "will the AGENT find one?". The agent cuts or resets its desk from
+# `origin/$MAIN`, so a brief committed nowhere — or committed locally and never
+# pushed — is invisible to it. Checking the working tree passes the gate and
+# hands over a slice whose specification is empty, which is the exact failure
+# this gate exists to prevent.
+#
+# THAT HOLDS ACROSS THE GATE'S MOVE, and is why the move cost this function
+# nothing: the desk was cut from `origin/$MAIN` when dispatch cut it and is cut
+# from `origin/$MAIN` now that the agent does. The ref the brief must be on did
+# not change, only who reads it there.
 #
 # Both directions were measured 2026-08-27. Running the filesystem check from a
 # checkout 8 commits behind main reported three branches' briefs missing while
@@ -326,6 +400,121 @@ brief_present() { # $1 = branch → 0 if a usable brief exists on origin/<main>
   [ "${sz:-0}" -gt 0 ]
 }
 
+# WHAT HAPPENS AFTER THE GATE FIRES. The gate above is correct and stays: a
+# missing brief still prepares and still refuses to start. What it never had is
+# a next step — it named the file, and every brief on this estate was then
+# written by hand.
+#
+# `Brief command` is that step, and it is a CONFIG KEY rather than a new script
+# for one reason: `/plot-implement` step 4 already owns brief authorship. A
+# script here would be a SECOND brief writer, and two writers drift. So the key
+# names how to run an agent headless — the shape `Idea command`, `Story command`
+# and `Approve command` already use — and the prompt it is handed asks for
+# `/plot-implement <slug>` and nothing else.
+#
+# ABSENT IS NOT AN ERROR. A project with no `Brief command` behaves exactly as
+# it does today: the gate refuses, and the refusal now names WHY nothing was
+# called — `no-brief-command`, the shape `commission.ts` gives `no-idea-command`.
+# `none` reads the same way as it does for `Worker command`: asked, and answered
+# "we write them by hand".
+brief_command() { # → the usable `Brief command`, or empty
+  local cmd
+  cmd=$("$script_dir/plot-config.sh" get "Brief command" "")
+  case "$cmd" in none|NONE|None) cmd="" ;; esac
+  printf '%s' "$cmd"
+}
+
+# Run the brief command for one branch, detached, and say what was done.
+#
+# DETACHED AND NOT WAITED ON, for the reason `commission.ts` gives: this is a
+# `claude -p` session of unknown length, and a fan-out that blocks on one would
+# hold every later branch behind it. The dispatch run reports that it asked; the
+# brief lands in a later commit, and the NEXT dispatch of the same branch starts
+# it. That is the whole loop.
+#
+# The prompt travels as ONE argument through `"$@"`, never interpolated into the
+# command string — `Brief command` is a shell FRAGMENT run through `sh -c`, so
+# anything spliced into it would be shell source. The slug is the only value
+# that reaches it and it is a plan slug, but the rule holds regardless of the
+# value: the safety is in the shape, not in the input.
+# WHAT THE AGENT IS ASKED FOR, and the one thing it must not be asked for.
+#
+# It is asked to run `/plot-implement <slug>`, and it is NOT asked to write a
+# brief in its own words. `/plot-implement` step 4 owns brief authorship; a
+# prompt that described the brief here would be a second author, and two
+# authors drift. The branch and the path are named because the skill writes for
+# one branch and the gate reads one path — `brief_path` is the same function
+# `brief_present` reads with, so writer and reader cannot disagree.
+#
+# It is told to COMMIT AND PUSH, because the gate reads `origin/<main>`. A brief
+# written and left in a working tree is invisible to the gate that asked for it,
+# and the next dispatch would ask again — a loop that writes a file every pass
+# and never starts a worker.
+brief_prompt() { # $1 = branch, $2 = slug
+  printf '/plot-implement %s — write the hand-off brief for branch `%s` at %s, then commit and push it to %s. The dispatch gate reads that path on origin/%s, so a brief left uncommitted is invisible to it.' \
+    "$2" "$1" "$(brief_path "$1")" "$MAIN" "$MAIN"
+}
+
+request_brief() { # $1 = branch, $2 = slug → 0 if a command was started
+  local branch="$1" bslug="$2" cmd log
+  cmd=$(brief_command)
+  if [ -z "$cmd" ]; then
+    echo "      no-brief-command — no \`Brief command\` in Plot Config, so nothing was asked to write it"
+    return 1
+  fi
+  log="$repo_root/.plot/brief-$(printf '%s' "${branch##*/}").log"
+  mkdir -p "$(dirname "$log")" 2>/dev/null || true
+  # `nohup ... &` inside a subshell, the same detachment `start_worker` uses:
+  # this outlives the dispatch run by design, because the fan-out must not block
+  # on a `claude -p` session of unknown length. `setsid` is not used — it does
+  # not exist on macOS, where most of this fleet runs.
+  ( cd "$repo_root" \
+    && PLOT_UNATTENDED=1 PLOT_PLAN_SLUG="$bslug" PLOT_BRIEF_BRANCH="$branch" \
+       nohup sh -c "$cmd \"\$@\"" plot-brief \
+       "$(brief_prompt "$branch" "$bslug")" \
+       >"$log" 2>&1 </dev/null & ) 2>/dev/null
+  echo "      asked the \`Brief command\` to write it — log: $log"
+  # SAYS WHAT WAS MEASURED, WHICH IS THE START AND NOT THE RESULT. The command
+  # is detached and never waited on, so this returns 0 the moment it is spawned
+  # and a command that fails in its first millisecond still counts. Measured
+  # 2026-09-02, first real use: the log held 33 bytes, `Unknown command:
+  # /plot-implement`, and the summary still reported `brief_asked=1`. Naming the
+  # log as the evidence is what keeps the count from reading as a promise.
+  echo "      started, not awaited — read the log to see whether it wrote anything"
+  echo "      dispatch $bslug again once it lands; the gate reads $(brief_ref "$branch")"
+  return 0
+}
+
+# STALENESS REPORTS AND NEVER REFUSES, and the measurement says why.
+#
+# Compared 2026-09-01, all three live briefs were older than their plans and all
+# three were CORRECT — every plan edit between them was bookkeeping (a PR
+# annotation, a measurement note, a re-measure before approval). A timestamp
+# gate would have refused 3 of 3 on the day it shipped, and a gate that refuses
+# everything is one people disable in its first week.
+#
+# It would also have missed the real case. The teardown brief was written AFTER
+# its plan and was still wrong, citing 80 `fs.rmSync` sites where the tree held
+# 76 — the CODE moved, not the plan. Freshness against the plan is the wrong
+# input: a brief's claims are about the repository, and nothing here compares
+# those to the repository. What would actually gate is judgement about which
+# numbers in a paragraph are claims, which grep cannot reach.
+#
+# So this prints a hint and SAYS it is a hint, naming the plan commit it
+# compared against so the reader can look at that commit rather than guess.
+brief_staleness_note() { # $1 = branch → prints a hint, or nothing
+  local branch="$1" bc pc bs ps
+  [ -n "$gate_sha" ] || return 0        # nothing shared to compare against
+  [ -n "${plan_path:-}" ] || return 0
+  bc=$(git log -1 --format='%H %ct' "$gate_ref" -- "$(brief_path "$branch")" 2>/dev/null) || return 0
+  pc=$(git log -1 --format='%H %ct' "$gate_ref" -- "$plan_path" 2>/dev/null) || return 0
+  [ -n "$bc" ] && [ -n "$pc" ] || return 0
+  bs=${bc##* }; ps=${pc##* }
+  [ "$bs" -lt "$ps" ] 2>/dev/null || return 0
+  echo "    brief older than the plan — a HINT, not a gate: the plan may have moved, or the edit may have been bookkeeping"
+  echo "      plan commit ${pc%% *} touched $plan_path after the brief's last change; read it before trusting the brief"
+}
+
 start_worker() {
   local branch="$1" wt="$2"
   local cmd
@@ -473,6 +662,23 @@ start_worker() {
   # single-quoted `sh -c` mangles a path with spaces, exactly as the exit file
   # already does.
   #
+  # AND THE WRAPPER WRITES IT ITSELF, from `$$` inside the `sh -c`. Until
+  # 2026-08-31 the dispatcher wrote `echo $!` beside the spawn, which named an
+  # intermediate subshell rather than the wrapper: three of three live workers
+  # measured that day recorded a pid one process above the agent's real parent
+  # (7357 against 7358, 71953 against 71954, 92947 against 92949).
+  #
+  # The cause is that `$!` names the last job THIS shell backgrounded, and with
+  # an env-var prefix in front of `nohup` bash cannot collapse the AND-list into
+  # one child — it forks a subshell, and that subshell is what `$!` reports.
+  # (Without the prefix bash `exec`s the command in place and `$!` is correct,
+  # which is why the shape matters and a smaller repro does not show it.)
+  #
+  # So the same rule the agent pid already follows applies here: THE PROCESS
+  # THAT KNOWS A PID IS THE ONE THAT WRITES IT. The wrapper knows `$$`; no
+  # ancestor can name it without guessing. It is written FIRST, before the
+  # monitors and the agent, so the file exists as early as it can.
+  #
   # The agent runs backgrounded inside the wrapper so the wrapper can capture its
   # `$!` and `wait` for it. There is a sub-millisecond window after the wrapper
   # starts and before it writes `.plot-worker.pid`; a scan landing in it reads an
@@ -522,6 +728,62 @@ start_worker() {
   # after it, then any stale copies of those lines are dropped and `startedAt` is
   # rewritten to the current run. This is exactly `stampManifest`, line for line,
   # which the parity test pins byte for byte.
+  #
+  # EVERY WORKER IS BORN MONITORED, AND THAT IS ENFORCED HERE OR NOWHERE.
+  #
+  # Three monitors start INSIDE the wrapper, as its children, immediately before
+  # the agent: one watches the process (`plot-worker-monitor.sh`), one watches
+  # the desk (`plot-agent-monitor.sh`), one watches the run
+  # (`plot-build-monitor.sh`). Each has a subject the others do not and a
+  # cadence it cannot share — seconds on the process table, minutes on the host,
+  # seconds again on a run but only while one is live.
+  #
+  # WHY INSIDE THE WRAPPER RATHER THAN BESIDE IT. The wrapper already outlives
+  # its agent by construction — it must, or there would be no exit code to
+  # write — so a child of it inherits that survival for free. Two processes
+  # started SIDE BY SIDE are independently mortal: the monitor could be killed
+  # or crash with nothing noticing, which is the failure being fixed one level
+  # up. `--stop` kills the agent; the monitors and the exit record survive it.
+  #
+  # WHY HERE RATHER THAN ANYWHERE ELSE. `start_worker` is the single path to a
+  # worker, which is what makes "every worker is born monitored" a gate rather
+  # than a rule: there is no other place to forget. Ask CLAUDE.md's test — *can
+  # you answer "did I attach a monitor?" without doing the work?* Here you
+  # cannot: no monitor start, no monitored worker, and a mutation test says so.
+  #
+  # ORDER, AND WHY IT IS THIS WAY ROUND. The monitors are backgrounded FIRST so
+  # they exist before their subject does; the agent is backgrounded next and
+  # `$!` is captured on the VERY NEXT command, because `$!` names the most
+  # recent background job and the pid file must name the AGENT. Starting a
+  # monitor between the agent and its `$!` would record a monitor's pid as the
+  # worker's — the panel bug the two-pid split already exists to prevent.
+  #
+  # THEY INHERIT THE STARTUP WINDOW RATHER THAN WIDENING IT. There is a
+  # sub-millisecond gap after the wrapper starts and before `.plot-worker.pid`
+  # is written, and a scan landing in it reads `none` — honest. The monitors
+  # start inside that same window; they must never turn an unwritten pid file
+  # into a `gone` finding, which is why the no-op reads no pid at all and the
+  # next slice treats an absent pid file as *not yet*.
+  #
+  # THE PATHS TRAVEL AS ENV VARS, like every other path the wrapper needs. The
+  # `sh -c` body is single-quoted and a path with spaces would not survive
+  # interpolation into it — the same reason the exit, pid and manifest paths are
+  # passed this way. An EMPTY value means "not attached", which is what keeps a
+  # missing script from turning into `command not found` in a detached shell
+  # nobody is reading.
+  #
+  # A HAND-MADE WORKTREE GETS NEITHER, and that falls out rather than being
+  # enforced: this is the only code that starts a wrapper, and a worktree with
+  # no wrapper has nothing for a monitor to be a child of.
+  local worker_monitor='' agent_monitor='' build_monitor=''
+  [ -x "$script_dir/plot-worker-monitor.sh" ] && worker_monitor="$script_dir/plot-worker-monitor.sh"
+  [ -x "$script_dir/plot-agent-monitor.sh" ] && agent_monitor="$script_dir/plot-agent-monitor.sh"
+  # THE THIRD MONITOR, born the same way and for the same reason. It watches the
+  # RUN — a Build is its own entity in the spec, so a monitor per entity is the
+  # pattern rather than an exception to it. Its cadence is the WorkerMonitor's
+  # 30 s rather than the AgentMonitor's 300 s, and it can afford that against a
+  # HOST because it asks nothing while no run is live.
+  [ -x "$script_dir/plot-build-monitor.sh" ] && build_monitor="$script_dir/plot-build-monitor.sh"
   local stamp_now
   stamp_now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
   ( cd "$wt" && PLOT_BRANCH="$branch" PLOT_WORKTREE="$wt" \
@@ -529,8 +791,12 @@ start_worker() {
       PLOT_SESSION_ID="$session" \
       PLOT_MANIFEST_FILE="$manifest_dir/$session.json" \
       PLOT_STAMP_STARTED="$stamp_now" \
+      PLOT_WORKER_MONITOR="$worker_monitor" \
+      PLOT_AGENT_MONITOR="$agent_monitor" \
+      PLOT_BUILD_MONITOR="$build_monitor" \
       PLOT_EXIT_FILE="$wt/.plot-worker.exit" PLOT_PID_FILE="$wt/.plot-worker.pid" \
-      nohup sh -c '( '"$cmd"' ) & agent=$!; printf "%s" "$agent" > "$PLOT_PID_FILE"; if [ -f "$PLOT_MANIFEST_FILE" ]; then awk -v pid="$agent" -v started="$PLOT_STAMP_STARTED" '"'"'
+      PLOT_WRAPPER_PID_FILE="$wt/.plot-worker.wrapper.pid" \
+      nohup sh -c 'printf "%s" "$$" > "$PLOT_WRAPPER_PID_FILE"; wmon=""; amon=""; bmon=""; if [ -n "$PLOT_WORKER_MONITOR" ]; then "$PLOT_WORKER_MONITOR" & wmon=$!; fi; if [ -n "$PLOT_AGENT_MONITOR" ]; then "$PLOT_AGENT_MONITOR" & amon=$!; fi; if [ -n "$PLOT_BUILD_MONITOR" ]; then "$PLOT_BUILD_MONITOR" & bmon=$!; fi; ( '"$cmd"' ) & agent=$!; printf "%s" "$agent" > "$PLOT_PID_FILE"; if [ -f "$PLOT_MANIFEST_FILE" ]; then awk -v pid="$agent" -v started="$PLOT_STAMP_STARTED" -v wrapper="$$" -v wmon="$wmon" -v amon="$amon" -v bmon="$bmon" '"'"'
         BEGIN { relaunch = 0; count = 1; stamped = 0 }
         FNR == NR {
           if ($0 ~ /^  "pid": "[^"]*",$/) {
@@ -545,18 +811,26 @@ start_worker() {
         !stamped && $0 ~ /^  "pid": "[^"]*",$/ {
           stamped = 1
           print "  \"pid\": \"" pid "\","
+          print "  \"wrapperPid\": \"" wrapper "\","
+          print "  \"workerMonitorPid\": \"" wmon "\","
+          print "  \"agentMonitorPid\": \"" amon "\","
+          print "  \"buildMonitorPid\": \"" bmon "\","
           if (relaunch) {
             print "  \"previousPid\": \"" displaced "\","
             print "  \"relaunches\": " count ","
           }
           next
         }
+        $0 ~ /^  "wrapperPid": "[^"]*",$/ { next }
+        $0 ~ /^  "workerMonitorPid": "[^"]*",$/ { next }
+        $0 ~ /^  "agentMonitorPid": "[^"]*",$/ { next }
+        $0 ~ /^  "buildMonitorPid": "[^"]*",$/ { next }
         relaunch && $0 ~ /^  "previousPid": "[^"]*",$/ { next }
         relaunch && $0 ~ /^  "relaunches": [0-9]+,$/ { next }
         relaunch && $0 ~ /^  "startedAt": "[^"]*"$/ { print "  \"startedAt\": \"" started "\""; next }
         { print }
       '"'"' "$PLOT_MANIFEST_FILE" "$PLOT_MANIFEST_FILE" > "$PLOT_MANIFEST_FILE.plot-pid-tmp" 2>/dev/null && mv "$PLOT_MANIFEST_FILE.plot-pid-tmp" "$PLOT_MANIFEST_FILE" 2>/dev/null || rm -f "$PLOT_MANIFEST_FILE.plot-pid-tmp"; fi; wait "$agent"; rc=$?; printf "%s" "$rc" > "$PLOT_EXIT_FILE"' \
-      >"$log" 2>&1 </dev/null & echo $! >"$wt/.plot-worker.wrapper.pid" )
+      >"$log" 2>&1 </dev/null & )
   echo "    started worker (log: $log)"
   return 0
 }
@@ -899,63 +1173,69 @@ if [ "$mode" = "migrate" ]; then
       continue
     fi
 
-    # TWO INDEPENDENT CONDITIONS, because the brief names two: a worktree moves
-    # only with NO LIVE WORKER **AND** NO UNLANDED WORK. They are separate
-    # measurements, exactly as they are in plot-reap.sh, and folding them into
-    # one verdict is a hole: plot_worker_state answers "is a WORKER running or
-    # waiting here", and it is keyed on the worker RECORDS (`.plot-worker.pid`,
-    # `.plot-worker.exit`). A hand-made worktree that never ran a Plot worker has
-    # no records and reads `none` no matter how dirty its tree is — and the
-    # hand-made worktrees are precisely the estate this mode exists to tidy. So
-    # liveness and unlanded-work are asked as two questions below.
-
-    # REFUSAL 1 & 2 — a LIVE WORKER, from the ONE shared answer. The brief is
-    # explicit: plot_worker_state is the single answer to "is a worker running
-    # in this worktree", sourced by both dispatch and the fleet scan. It carries
-    # what a bare `ps` cannot — pid-reuse detection via the manifest's
-    # `startedAt`, and the `waiting` state a PLOT-BLOCKED* marker produces.
-    # Re-implementing either here is the drift the codebase fought to remove.
+    # FOUR READINGS, GATHERED HERE AND DECIDED ELSEWHERE. This block holds no
+    # `if` about whether a worktree may move; it collects what was measured and
+    # `plot-movable.mjs` returns the refusal. The four were shell `if`s until
+    # 2026-09-01, and nothing could trigger one in isolation — least of all the
+    # combinations this estate will not produce on demand, a live pid and a
+    # dirty tree at once.
+    #
+    # LIVENESS AND UNLANDED WORK STAY TWO SEPARATE MEASUREMENTS, exactly as they
+    # were: plot_worker_state answers "is a process running or waiting here" and
+    # is keyed on the records a dispatch writes (`.plot-worker.pid`,
+    # `.plot-worker.exit`). A hand-made worktree that never ran one reads `none`
+    # however dirty its tree is — and hand-made worktrees are precisely the
+    # estate this mode exists to tidy. The rule reads them as two fields for
+    # that reason.
+    #
+    # plot_worker_state is the ONE liveness answer, sourced by both this script
+    # and the fleet scan. It carries what a bare `ps` cannot — pid-reuse
+    # detection via the manifest's `startedAt`, and the `waiting` state a
+    # PLOT-BLOCKED* marker produces.
     wstate_row=$(plot_worker_state "$wt")
     state=$(printf '%s' "$wstate_row" | cut -f1)
-    case "$state" in
-      running)
-        pid=$(printf '%s' "$wstate_row" | cut -f2)
-        printf '%-8s %-52s %s\n' "keep" "$(basename "$wt")" "worker alive (pid $pid)"
-        n_skipped=$((n_skipped + 1))
-        continue ;;
-      waiting)
-        # The shared classifier reports `waiting` when a blocked marker exists:
-        # a worker stopped to ask a person something. Moving it breaks the
-        # checkout the answer is owed to.
-        printf '%-8s %-52s %s\n' "keep" "$(basename "$wt")" "blocked marker — needs a person"
-        n_skipped=$((n_skipped + 1))
-        continue ;;
-    esac
+    pid=$(printf '%s' "$wstate_row" | cut -f2)
 
-    # REFUSAL 3 — UNCOMMITTED WORK, measured independently of any worker record.
     # `plot_worker_dirty` applies the shared filter (editor leftovers and Plot's
-    # own bookkeeping do not count), so this fires on real work only.
+    # own bookkeeping do not count), so this reads real work only.
     dirty=$(plot_worker_dirty "$wt" | head -1 | cut -c1-40)
-    if [ -n "$dirty" ]; then
-      printf '%-8s %-52s %s\n' "keep" "$(basename "$wt")" "uncommitted: $dirty"
-      n_skipped=$((n_skipped + 1))
-      continue
-    fi
 
-    # REFUSAL 4 — UNPUSHED COMMITS. Work that exists only on this machine.
-    # Only the branch's OWN upstream answers "pushed?"; an absent upstream leaves
-    # the question unanswerable, and an unanswered question is not a refusal —
-    # the same principle plot_worker_task_state reached the hard way (counting
-    # against origin/main marked every clean branch stalled in a remote-less
-    # repo). So no upstream falls through to "movable", not to "keep".
+    # Only the branch's OWN upstream answers "pushed?". An absent upstream
+    # leaves the field EMPTY, which the rule reads as unanswerable rather than
+    # as zero — and an unanswered question is not a refusal, the principle
+    # plot_worker_task_state reached the hard way when counting against
+    # origin/main marked every clean branch stalled in a remote-less repo.
+    ahead=""
     if [ -n "$br" ]; then
       ahead=$(git -C "$wt" rev-list --count '@{upstream}..HEAD' 2>/dev/null || echo "")
-      case "$ahead" in
-        ''|0|*[!0-9]*) ;;  # no upstream, or nothing ahead: not a refusal
-        *) printf '%-8s %-52s %s\n' "keep" "$(basename "$wt")" "unpushed commits ($ahead ahead)"
-           n_skipped=$((n_skipped + 1))
-           continue ;;
+    fi
+
+    # THE DECISION. One call per tree, and the answer is a named refusal.
+    #
+    # A rule that cannot be asked REFUSES: a missing `node`, a missing bundle or
+    # a throwing module all leave `mv_verdict` empty, and an empty verdict keeps
+    # the worktree and says the rule could not be asked. Silence is never
+    # permission — and here the permissive direction moves a checkout an agent
+    # may be writing to, which `git worktree move` breaks mid-run.
+    mv_verdict=$(printf '%s\t%s\t%s\t%s' "$state" "$pid" "$dirty" "$ahead" \
+      | node "$script_dir/board/plot-movable.mjs" 2>/dev/null || true)
+    mv_refusal=${mv_verdict%%$'\t'*}
+    mv_detail=${mv_verdict#*$'\t'}
+
+    # RENDERING, not deciding. The rule named the measurement; this names what
+    # it means to someone reading the table, which is the caller's half because
+    # only the caller knows it is printing one.
+    if [ "$mv_refusal" != "move" ]; then
+      case "$mv_refusal" in
+        live-worker)         reason="worker alive (pid $mv_detail)" ;;
+        blocked-marker)      reason="blocked marker — needs a person" ;;
+        uncommitted-changes) reason="uncommitted: $mv_detail" ;;
+        unpushed-commits)    reason="unpushed commits ($mv_detail ahead)" ;;
+        *)                   reason="rule could not be asked — keeping" ;;
       esac
+      printf '%-8s %-52s %s\n' "keep" "$(basename "$wt")" "$reason"
+      n_skipped=$((n_skipped + 1))
+      continue
     fi
 
     # This worktree is idle — it can be moved.
@@ -1205,6 +1485,194 @@ esac
 # MAIN was resolved and origin fetched above, before the phase gate — the gate
 # needs the shared ref to read the plan from it.
 
+# ---------------------------------------------------------------------------
+# THE PREREQUISITE GATE: a branch that waits on another plan's branch
+# ---------------------------------------------------------------------------
+#
+# A plan may annotate one of its branches `<!-- waits: <branch> -->`, naming ONE
+# branch — usually of another plan — that must merge before this one may start.
+# The parser exposes it as `waves[].branches[].waits_on`; the scan turns it into
+# the branch states `waiting` and `blocked`, so `--next` already stops OFFERING
+# such a branch.
+#
+# THAT IS ONE HALF, AND THIS IS THE OTHER. An empty offer has nothing to say
+# about what it filtered out: `plot-dispatch.sh <slug>` answered `dispatched=0`
+# with no reason attached, which is the same silence `--restart` was built to
+# break. So this names the branch AND the prerequisite, and it names them in
+# `--dry-run` identically to a real run.
+#
+# IT HAS COST TWO WORKERS. Measured 2026-09-02:
+# `feature/the-domain-forgets-the-vendor-list` was re-dispatched at 04:50 into a
+# prerequisite that had not merged, hit its own gate, and wrote a PLOT-BLOCKED
+# marker. Its report names the cause: *"plot-dispatch.sh gates on the plan's
+# phase, and this plan is Approved, so the slice read as eligible."*
+#
+# THE ANNOTATION IS READ FROM THE SHARED REF, out of the same `gate_meta` the
+# phase gate parsed. A `waits:` that exists only in this working tree is an
+# ordering constraint nobody else can see, exactly as a local approval is.
+#
+# THE PREREQUISITE IS ASKED OF THE HOST, NEVER OF THE REFS.
+# `plot-release-refs.sh` deletes the remote refs of a delivered plan's merged
+# branches, so a prerequisite that SUCCEEDED and was then reaped has no ref —
+# and a rule reading refs would hold its dependent forever BECAUSE its
+# dependency succeeded. That is the worst available failure: correct work
+# producing a permanent block. `pr-state` answers about PULL REQUESTS, and a
+# merged PR outlives the branch it was cut from.
+#
+# `NONE` AND SILENCE ARE DIFFERENT ANSWERS. `NONE` means the host was asked and
+# has never seen a PR for that branch — a typo, which is `blocked`. A host that
+# could not be asked is neither permission nor proof of a typo, so it HOLDS the
+# branch at `waiting`. Both refuse; only one tells the operator to fix the plan.
+
+# What the host says about the prerequisite's pull requests.
+#
+# Four answers, and the last two must never be collapsed — see the header
+# above. `--offline` promises no network, so it answers `unreachable`: the
+# question was not put, and a flag that lied would be worse than a slower
+# answer. The same reasoning `reached_review` applies one screen up.
+prereq_answer() { # $1=prerequisite branch → merged|unmerged|none|unreachable
+  local js st
+  [ -z "$offline" ] || { echo unreachable; return; }
+  [ "$("$script_dir/plot-host.sh" backend 2>/dev/null)" != "none" ] || { echo unreachable; return; }
+  # Exit code first: a non-zero is a transport failure and its stdout is not an
+  # answer. GitHub returned 503 all afternoon on 2026-08-17, and a reader that
+  # trusted the payload on failure would have started every waiting branch.
+  js=$("$script_dir/plot-host.sh" pr-state "$1" </dev/null 2>/dev/null) || { echo unreachable; return; }
+  st=$(printf '%s' "$js" | sed -n 's/.*"state":"\([A-Z]*\)".*/\1/p')
+  case "$st" in
+    MERGED) echo merged ;;
+    NONE)   echo none ;;
+    # OPEN and CLOSED both mean the host has SEEN the branch. A closed, unmerged
+    # PR is `unmerged` rather than `none`: nothing is misspelled — somebody
+    # withdrew the work, and that resolves by reopening it, not by editing the
+    # plan.
+    OPEN|CLOSED) echo unmerged ;;
+    # A state word this adapter does not emit, or none at all. Unread is not
+    # answered, and this gate's silence holds rather than permits.
+    *) echo unreachable ;;
+  esac
+}
+
+# Every branch the plan annotates `waits:`, with what it waits on — read from
+# the same blob, in the plan's own order, one line of `branch<TAB>prerequisite`.
+#
+# NON-DEFERRED ONLY. `deferred:` is a JUDGEMENT — somebody gave the branch up —
+# and it outranks a wait for the same reason the scan lets it: a branch nobody
+# will start does not need to be told what it is waiting for. The two
+# annotations sit on one line and neither reads the other's value.
+waits_pairs() { # → branch<TAB>prerequisite, one per annotated branch
+  printf '%s' "$gate_meta" | awk '
+    {
+      n = split($0, parts, /\{"branch":"/)
+      for (i = 2; i <= n; i++) {
+        rec = parts[i]
+        br = rec; sub(/".*$/, "", br)
+        if (rec ~ /"deferred":true/) continue
+        if (match(rec, /"waits_on":"[^"]*"/)) {
+          w = substr(rec, RSTART + 12, RLENGTH - 13)
+          if (w != "") print br "\t" w
+        }
+      }
+    }'
+}
+
+# THE PREFLIGHT, run once before the fan-out, and it is where the REFUSAL lives.
+#
+# WHY IT CANNOT LIVE IN THE LOOP ALONE. The fan-out loop only ever sees what
+# `plot-fleet-scan.sh` offered, and the scan ALREADY reports a waiting branch as
+# `waiting` rather than `open` — so it is filtered out before this script hears
+# of it, and the run ends `dispatched=0 skipped=0` with nothing said about what
+# was withheld. That silence is the exact defect: an empty offer has nothing to
+# say about what it filtered out, and a worker was dispatched twice on 2026-09-02
+# by an operator reading it as "nothing to do here".
+#
+# So the plan is walked DIRECTLY. This script already holds the parsed plan from
+# the shared ref — the same blob its phase gate read — so naming what the fan-out
+# will not reach costs one host call per annotated branch, on a population of six
+# plans in 188.
+#
+# IT FILLS `waits_held`, WHICH THE LOOPS THEN CONSULT. Two mechanisms, one
+# decision: this states the refusal, and the loops refuse to write for a branch
+# it named — belt to that brace, because a scan that could not reach the host
+# still offers the branch as `open`.
+declare -a waits_held=()
+is_waits_held() {
+  local x
+  for x in ${waits_held[@]+"${waits_held[@]}"}; do [ "$x" = "$1" ] && return 0; done
+  return 1
+}
+
+# AND IT FILLS `waits_freed`, WHICH IS WHERE `--allow-waiting` GETS ITS
+# CANDIDATE FROM.
+#
+# The override cannot work by relaxing a test in this script, because the branch
+# never reaches a test here: `plot-fleet-scan.sh` reports a waiting branch as
+# `waiting` rather than `open`, so `--list-eligible` and `--next` both withhold
+# it and the loops are handed an empty set. Measured 2026-09-02 — the flag
+# printed its override line and the run still reported `dispatched=0 skipped=0`,
+# counting the branch neither way.
+#
+# So the flag ADDS a candidate rather than removing a filter. The preflight
+# already walked the plan from the shared ref and asked the host about the
+# prerequisite, so it holds the one fact the scan withheld, and naming it here
+# costs no further call.
+#
+# ONLY A BRANCH THE PREFLIGHT ITSELF HELD, and only under the flag. This adds
+# nothing the scan refused for any OTHER reason — a claimed branch, a `wip` one,
+# an incomplete prior wave — because those verdicts are not this flag's to
+# override and the scan remains the only thing that decides them. The branch
+# still passes every gate the loops apply after it: `held_worktree`, the claim
+# race, and the brief.
+declare -a waits_freed=()
+is_waits_freed() {
+  local x
+  for x in ${waits_freed[@]+"${waits_freed[@]}"}; do [ "$x" = "$1" ] && return 0; done
+  return 1
+}
+
+# Runs the preflight: prints its refusals, fills `waits_held`, and adds what it
+# withheld to `n_skipped`.
+#
+# NOT A COMMAND SUBSTITUTION, and that is not a style choice. `$( … )` is a
+# SUBSHELL, so an array filled inside one is discarded on return — the loops
+# below would consult an empty `waits_held` and the refusal would be a message
+# with no effect behind it. So this writes its two results into globals and the
+# caller invokes it plainly.
+#
+# PRINTED IDENTICALLY BY --dry-run AND THE REAL RUN, the discipline `report_held`
+# already sets: a dry run that offers what a real run would refuse is worse than
+# no dry run — it is the same wrong answer with a reassurance attached.
+run_waits_preflight() { # → prints refusals; fills waits_held, adds to n_skipped
+  local br prereq answer held
+  while IFS=$'\t' read -r br prereq; do
+    [ -n "$br" ] || continue
+    answer=$(prereq_answer "$prereq")
+    case "$answer" in
+      merged) continue ;;
+      none)   held=blocked ;;
+      *)      held=waiting ;;
+    esac
+    # `--allow-waiting` SAYS SO ON THE LINE IT OVERRIDES. An override nobody can
+    # see in the output is an override nobody can audit.
+    if [ "$allow_waiting" = 1 ]; then
+      echo "$br waits on $prereq ($held) — dispatching anyway (--allow-waiting)"
+      waits_freed+=("$br")
+      continue
+    fi
+    waits_held+=("$br")
+    n_skipped=$((n_skipped + 1))
+    if [ "$held" = "blocked" ]; then
+      echo "skipped $br (blocked — no PR found for $prereq)"
+      echo "  the plan says this branch waits on $prereq, and the host has never"
+      echo "  seen a pull request for it. Check the branch name in the plan."
+    else
+      echo "skipped $br (waiting on $prereq)"
+      echo "  the plan says this branch waits on $prereq, which has not merged."
+      echo "  Dispatch it when that lands, or pass --allow-waiting to start anyway."
+    fi
+  done < <(waits_pairs)
+}
+
 # Where the worktrees live and what their names carry — see resolve_wt_root.
 # The default is beside the repo with the `plot-wt-` prefix; a `Worktree root:`
 # key relocates them (and drops the prefix, which was only earning its keep
@@ -1215,6 +1683,7 @@ repo_root=$(git rev-parse --show-toplevel)
 resolve_wt_root "$repo_root"
 
 n_dispatched=0 n_reused=0 n_skipped=0 n_started=0
+n_brief_asked=0
 
 # Whether this run COULD have started anything, read once and up front.
 #
@@ -1249,31 +1718,20 @@ worker_state_field() {
   fi
 }
 
-# The summary block: an optional prose line, then the machine-countable footer.
+# The summary: the machine-countable footer, and nothing above it.
+#
+# THE PROSE LINE IS GONE, BY ITS OWN RULE. It existed to explain a zero that
+# had a cause worth naming — a `Worker command` nobody had configured, read off
+# a run that had prepared desks and staffed none. Dispatch starts no worker at
+# all now, so `started=0` is structural: the line would print on every run,
+# always true and never informative. `--dry-run` was held to exactly this rule
+# from the start — *"a dry run starts nothing BY CONSTRUCTION, so it explains
+# nothing"* — and the fan-out has become the same case.
 #
-# The prose line is printed only when there is a consequence to state — a
-# summary that always explains itself teaches the reader to skip it, and then
-# it is worth nothing on the day it matters. `worktrees prepared` counts
-# dispatched + reused, because a re-adopted worktree is equally a desk nobody
-# was sat at.
+# `worker=` still travels in the footer. It says how this repo is configured,
+# which remains a fact about the repo even where it no longer explains a count.
 print_summary() { # $1=dispatched $2=reused $3=skipped $4=started
-  local prepared=$(( $1 + $2 )) worker
-  worker=$(worker_state_field)
-  if [ "$prepared" -gt 0 ] && [ "$4" = 0 ]; then
-    case "$worker" in
-      unconfigured)
-        echo "$prepared worktree$([ "$prepared" = 1 ] || echo s) prepared, 0 workers started, no \`Worker command\` configured" ;;
-      declined)
-        # Asked and answered: this repo starts its workers by hand. Stating the
-        # count without calling it a gap — hand-starting is a legitimate
-        # workflow, and repeating "not configured" at someone who decided that
-        # on purpose is the nag the plan rules out.
-        echo "$prepared worktree$([ "$prepared" = 1 ] || echo s) prepared, 0 workers started — this repo starts them by hand" ;;
-      suppressed)
-        echo "$prepared worktree$([ "$prepared" = 1 ] || echo s) prepared, 0 workers started (--no-start)" ;;
-    esac
-  fi
-  echo "summary: dispatched=$1 reused=$2 skipped=$3 started=$4 brief=missing worker=$worker"
+  echo "summary: dispatched=$1 reused=$2 skipped=$3 started=$4 brief=missing worker=$(worker_state_field) brief_asked=${n_brief_asked:-0}"
 }
 
 # ---------------------------------------------------------------------------
@@ -1345,7 +1803,7 @@ update_parallel_agents_cap() { # $1 = new cap
   if [ -f "$FLEET_CONTROLS_FILE" ]; then
     # Preserve the existing autoDispatch setting
     local existing
-    existing=$(sed -n 's/.*"autoDispatch"[[:space:]]*:[[:space:]]*\(true\|false\).*/\1/p' "$FLEET_CONTROLS_FILE" | head -1)
+    existing=$(sed -nE 's/.*"autoDispatch"[[:space:]]*:[[:space:]]*(true|false).*/\1/p' "$FLEET_CONTROLS_FILE" | head -1)
     [ -n "$existing" ] && auto_dispatch="$existing"
   fi
 
@@ -1470,14 +1928,39 @@ write_started_record() { # $@ = branches
   fi
 
   if [ -f "$tmpwt/$rel" ]; then
-    local br
+    local br wrote=0
     for br in "$@"; do
+      # A BRANCH ALREADY RECORDED IS NOT RECORDED AGAIN, and this check is what
+      # the CLAIM used to do. Dispatch pushed a claim, a claimed branch was
+      # never offered again, and a second run therefore booked nothing — the
+      # idempotence was a side effect of the lock rather than a property of the
+      # record. The claim went with the fan-out's writes, so the record owns its
+      # own idempotence now: a plan dispatched three times must not read as
+      # started three times, or the count drifts from the refs it describes.
+      #
+      # MATCHED ON THE BRANCH IN BACKTICKS, the shape `append_started_line`
+      # writes and `plot-plan-meta.sh` parses. A bare substring match would let
+      # `feature/api` find itself inside `feature/api-v2`.
+      if grep -qF -- "\`$br\`" "$tmpwt/$rel" 2>/dev/null \
+         && grep -q -- "Started:.*\`$br\`" "$tmpwt/$rel" 2>/dev/null; then
+        continue
+      fi
       append_started_line "$tmpwt/$rel" "$date" "$who" "$br" || {
         echo "plot-dispatch: $rel has no '## Status' section — nowhere to record" >&2
         rc=1
         break
       }
+      wrote=1
     done
+    # NOTHING NEW TO SAY IS NOT A FAILURE. Every branch this run handed over was
+    # already on the record, so there is no commit to make and no push to
+    # attempt — and a run that pushed an empty commit would leave one per
+    # re-dispatch on the default branch.
+    if [ "$rc" = 0 ] && [ "$wrote" = 0 ]; then
+      git worktree remove --force "$tmpwt" 2>/dev/null || true
+      git branch -D "$bookbr" >/dev/null 2>&1 || true
+      return 0
+    fi
     if [ "$rc" = 0 ]; then
       git -C "$tmpwt" add -- "$rel" 2>/dev/null
       git -C "$tmpwt" -c "user.name=$who" commit -q \
@@ -1538,6 +2021,23 @@ real_plan_path() { # $1=plan file as found (possibly a symlink, possibly relativ
 append_started_line() { # $1=file $2=date $3=who $4=branch
   local f="$1" line
   line="- **Started:** $2, $3, \`$4\`"
+
+  # ALREADY RECORDED IS NOT AN ERROR — it is a second dispatch of the same
+  # slice, and this returns 0 having written nothing.
+  #
+  # THE CLAIM USED TO BE THIS GUARD. A dispatched branch was claimed by a ref
+  # push, so `--next` never offered it twice and a re-run booked nothing. The
+  # hand-over pushes no claim, so the branch stays `open` and every re-run
+  # reaches this line: measured 2026-09-04, two runs left two identical
+  # `Started:` records in one plan.
+  #
+  # The DATE is deliberately not matched. A slice handed over again tomorrow is
+  # the same start, and a per-day record would drift from the refs it describes
+  # exactly as a per-run one does.
+  if grep -qF -- "\`$4\`" "$f" 2>/dev/null \
+    && grep -q -- "^[ \t]*[-*][ \t]*\*\*Started:\*\*.*\`$4\`" "$f" 2>/dev/null; then
+    return 0
+  fi
   awk -v line="$line" '
     { lines[++n] = $0 }
     END {
@@ -1772,7 +2272,38 @@ held_worktree() { # $1=branch → prints the worktree path when held, else nothi
   # in-flight report a few lines up.
   [ -z "$(uncommitted_files "$wt")" ] || { printf '%s' "$wt"; return 0; }
 
-  # Its tip landed already — a leftover desk, not a held one.
+  # DID ITS WORK LAND? THE HOST ANSWERS, NOT ANCESTRY.
+  #
+  # This asked `git merge-base --is-ancestor "$br" "origin/$MAIN"` until
+  # 2026-09-04. Measured that day on this estate: ten merged branches still
+  # carried a remote ref and ancestry disagreed with the host on TEN OF TEN.
+  # Squash-merge is not occasionally wrong here — the squashed commit is not the
+  # branch's commit, so the branch stays ahead of main forever and ancestry
+  # answers "not landed" about every squash-merged branch there is.
+  #
+  # The failure direction is throughput, not safety: ancestry called a landed
+  # leftover HELD, so dispatch refused a branch that was free. That is the
+  # cheap half of the plan's measurement and it is still a refusal an operator
+  # has to route around.
+  #
+  # `pr_merged` is the ONE answer, sourced rather than re-derived — the same
+  # gate `plot-reap.sh` and `plot-release-refs.sh` read, for the reason that
+  # file states: two implementations of one question drift, and one of them
+  # drifts permissive.
+  #
+  # ANCESTRY REMAINS AS A SECOND CHANCE, and only toward "landed". A
+  # fast-forward or rebase merge leaves the tip genuinely in main while the host
+  # may hold no PR at all — a branch pushed straight to main, which this repo's
+  # own fixtures do. It can only ever release a worktree the host already
+  # declined to release, so it adds no way to refuse and no way to hide work.
+  #
+  # AN UNREACHABLE HOST ANSWERS "NOT MERGED", which keeps the worktree held.
+  # That is `pr_merged`'s documented direction and the right one here too:
+  # silence is never permission to hand somebody's desk to a second agent.
+  # plot-ancestry: prefilter — second only to `pr_merged` above, and it can
+  # only RELEASE a worktree the host already declined to release. It adds no
+  # refusal, so a squash merge it misreads changes nothing.
+  pr_merged "$br" && return 1
   git merge-base --is-ancestor "$br" "origin/$MAIN" </dev/null 2>/dev/null && return 1
   printf '%s' "$wt"
 }
@@ -1839,6 +2370,37 @@ work_in_flight() { # $1=branch to exclude (the candidate)
 IN_FLIGHT_MAX_FILES=6
 IN_FLIGHT_MAX_BRANCHES=8
 
+# What a real run would attach, named per worktree — behind `--monitors`.
+#
+# SILENT UNLESS ASKED, which is what keeps the default `--dry-run` output
+# byte-identical to a run from before the monitors existed. That diff is this
+# slice's protection against the one failure that matters here: a mistake in
+# `start_worker` starts no workers at all, and the dry run exercises every
+# refusal against real worktrees and real pids without starting anything.
+#
+# IT NAMES THE SCRIPT PATH, not just the monitor. The question a reader has at
+# a dry run is *which code would run against my worktree* — a bare "2 monitors"
+# would send them into this script to find out, and a path they can `cat` is
+# the same courtesy the manifest refusal above pays by naming its directory.
+#
+# IT REPORTS ABSENCE TOO. A monitor script that is missing or non-executable
+# means an unmonitored worker, and the empty env var that produces is invisible
+# at launch by design (a detached `sh -c` nobody reads must not spew `command
+# not found`). The dry run is the one place that silence can be made audible
+# before it matters.
+report_monitors() { # $1=worktree
+  [ "$show_monitors" = 1 ] || return 0
+  local wt="$1" m
+  for m in worker agent; do
+    local script="$script_dir/plot-$m-monitor.sh"
+    if [ -x "$script" ]; then
+      echo "  would attach: $script → $wt"
+    else
+      echo "  would attach NOTHING for the $m monitor — $script is missing or not executable"
+    fi
+  done
+}
+
 report_in_flight() { # $1=candidate branch
   local br files shown extra n=0 total
   total=$(work_in_flight "$1" | wc -l | tr -d ' ')
@@ -1867,6 +2429,13 @@ report_in_flight() { # $1=candidate branch
   done
 }
 
+# THE PREREQUISITE PREFLIGHT, before either fan-out path. It names every branch
+# this plan will not start and why, and fills `waits_held` so neither loop can
+# write for one. Run here, once, rather than inside the loops: the scan filters a
+# waiting branch out before a loop ever hears of it, so a refusal that only fires
+# on an offered branch would never fire at all.
+run_waits_preflight
+
 # A dry run changes nothing, so nothing can go stale — read the whole eligible
 # set once. (`--next` would loop forever here: without a claim it keeps
 # returning the same branch.)
@@ -1881,10 +2450,21 @@ if [ "$dry_run" = 1 ]; then
       n_skipped=$((n_skipped + 1))
       continue
     fi
+    # ALREADY REFUSED BY THE PREFLIGHT, which named it and counted it. The
+    # scan does not normally offer a waiting branch at all; this arm catches
+    # the one that reached here because the scan could not ask the host.
+    is_waits_held "$br" && continue
     echo "would dispatch $br → $(worktree_for "$br")"
+    report_monitors "$(worktree_for "$br")"
     report_in_flight "$br"
     n_dispatched=$((n_dispatched + 1))
-  done < <("$script_dir/plot-fleet-scan.sh" $offline --list-eligible "$slug" 2>/dev/null)
+    # The scan's eligible set, plus whatever `--allow-waiting` freed. The scan
+    # reports a waiting branch as `waiting`, so it is absent from the first and
+    # only the preflight can supply it — see `waits_freed`. `sort -u` because a
+    # branch the scan DID offer (its host call failed where the preflight's
+    # succeeded) must be dispatched once, not twice.
+  done < <({ "$script_dir/plot-fleet-scan.sh" $offline --list-eligible "$slug" 2>/dev/null
+             printf '%s\n' ${waits_freed[@]+"${waits_freed[@]}"}; } | grep -v '^$' | sort -u)
   # A dry run starts nothing BY CONSTRUCTION, so its `started=0` carries no
   # information about the config — reporting "no workers started" here would be
   # true and useless, and would train the reader to skip the line on the real
@@ -1892,42 +2472,82 @@ if [ "$dry_run" = 1 ]; then
   # `skipped` is REAL here, not a constant. A dry run refuses held branches
   # exactly as the real run does, so its count is a fact about this fleet — and
   # it was hardcoded to 0 until the gate gave it something to count.
-  echo "summary: dispatched=$n_dispatched reused=0 skipped=$n_skipped started=0 brief=missing worker=$(worker_state_field)"
+  # `brief_asked=0` is a CONSTANT here and not a prediction. A dry run changes
+  # nothing, and asking the `Brief command` to write a brief spawns an agent
+  # that commits — the loudest write in this script. The field travels so the
+  # footer's shape does not depend on the mode a machine reader happened to
+  # call in.
+  echo "summary: dispatched=$n_dispatched reused=0 skipped=$n_skipped started=0 brief=missing worker=$(worker_state_field) brief_asked=0"
   exit 0
 fi
 
-# Ask the fleet scan for eligible-and-unclaimed branches, one at a time.
-# Re-asking after each claim is deliberate (pull, not push): the answer changes
-# as we claim, and a list computed up front would go stale mid-fan-out.
-while :; do
+# THE LIST IS READ ONCE, AND THAT FOLLOWS FROM THE CLAIM GOING.
+#
+# This was a PULL: `--next` was asked again after every claim, because claiming
+# a branch changed what the next ask would offer and a list computed up front
+# would have gone stale mid-fan-out. Dispatch claims nothing now — it hands a
+# slice to the registry and returns — so nothing this loop does changes the
+# scan's answer, and re-asking would return the same branch until a gate marked
+# it exhausted and the loop broke on it. Measured on the first run after the
+# claim was removed: `feature/one` handed over, `feature/two` never reached.
+#
+# ONE SCAN RATHER THAN N. The scan is 18.3 s here, so the pull cost one of those
+# per branch to re-derive an answer that could not have moved.
+#
+# `--allow-waiting`'s CANDIDATES COME LAST, after every branch the scan was
+# willing to name. `--list-eligible` reports a waiting branch as `waiting` and
+# never offers it, so the flag's candidates can only come from the preflight; a
+# held branch is one the operator chose to start early and must not displace one
+# that was ready. `sort -u` because a branch the scan DID offer — its host call
+# failed where the preflight's succeeded — must be handed over once, not twice.
+#
+# A `while read` LOOP, BECAUSE macOS SHIPS BASH 3.2. The bash 4 builtin that
+# reads a stream into an array does not exist there, and
+# `test/reconcile/mergequeue.test.mjs` gates on it — by grepping these scripts,
+# so naming the builtin in a comment fails the gate too.
+#
+# The single scan this block exists for is unaffected: the subshell still runs
+# once, and its output is still read once.
+fan_out=()
+while IFS= read -r _line; do
+  fan_out+=("$_line")
+done < <({ "$script_dir/plot-fleet-scan.sh" $offline --list-eligible "$slug" 2>/dev/null
+           [ "$allow_waiting" = 1 ] && printf '%s\n' ${waits_freed[@]+"${waits_freed[@]}"}
+           :; } | grep -v '^$' | sort -u)
+
+for branch in ${fan_out[@]+"${fan_out[@]}"}; do
   [ "$max" -gt 0 ] && [ "$n_dispatched" -ge "$max" ] && break
-
-  branch=$("$script_dir/plot-fleet-scan.sh" $offline --next "$slug" 2>/dev/null) || break
-  [ -n "$branch" ] || break
-  # --next has no memory; if it offers something we already failed on, the
-  # eligible set is exhausted for this run.
-  is_exhausted "$branch" && break
-
-  # Flatten the whole branch name, not just its last segment: feature/api and
-  # bug/api are different work and must not share a worktree (a shared path
-  # also makes --stop act on whichever claimed it first).
+  # `exhausted` SURVIVES THE PULL IT WAS WRITTEN FOR. It no longer has to stop
+  # the loop re-offering a branch — a list cannot — but the gates below still
+  # mark what they refused, and `sort -u` cannot merge a preflight candidate
+  # with a scan-offered one where the two spellings differ.
+  is_exhausted "$branch" && continue
+
+  # THE PATH DISPATCH NO LONGER CREATES, still composed for the two readers that
+  # need it: the dry run, which names where a desk WOULD go, and the monitor
+  # report. The agent decides its own desk now, so this is a prediction rather
+  # than a destination — and it stays flattened whole, because `feature/api` and
+  # `bug/api` are different work and must not name one directory.
   suffix=$(printf '%s' "$branch" | tr '/' '-')
   wt="$wt_root/$wt_prefix$suffix"
 
   if [ "$dry_run" = 1 ]; then
-    echo "would dispatch $branch → $wt"
+    echo "would hand over $branch → the registry"
+    report_monitors "$wt"
     report_in_flight "$branch"
     n_dispatched=$((n_dispatched + 1))
     continue
   fi
 
-  # THE HELD-BRANCH GATE, ahead of every write this loop makes.
+  # THE HELD-BRANCH GATE, and it survives the fan-out losing its writes.
   #
-  # Ahead of the adoption path below in particular: `reusing existing worktree`
-  # is right for a desk THIS script laid out and a worker has since finished
-  # with, and wrong for one an operator opened by hand and is still using — and
-  # by tip alone those two are the same directory. Unlanded work is what
-  # separates them, so the gate asks first and adoption only sees what is left.
+  # It refuses a branch whose own desk holds work that has not landed, and that
+  # is a MEASUREMENT of somebody sitting at it — not a prediction about a file.
+  # Dispatch creates no desk any more, so this no longer protects an adoption
+  # path; it protects the hand-over itself. Handing a slice to the registry
+  # while an agent is mid-edit on that branch is how two agents end up on one,
+  # and the desk is the only place that work is visible: it is unpushed by
+  # definition, so no ref and no PR reports it.
   #
   # `exhausted` is what makes the refusal terminal: --next has no memory and
   # would keep offering this same branch until the loop's own break fired.
@@ -1938,80 +2558,104 @@ while :; do
     continue
   fi
 
-  # BEFORE the worktree exists. Once dispatch has created this candidate's
-  # worktree and claim, the candidate is itself work in flight, and a report
-  # taken afterwards would describe the fan-out rather than what preceded it.
+  # ALREADY REFUSED BY THE PREFLIGHT, and still asked here. A slice handed over
+  # while its prerequisite is unmerged is an agent started on work that cannot
+  # build, and `feature/the-domain-forgets-the-vendor-list` is the measured
+  # case — claimed, and holding nothing but its claim commit.
+  #
+  # `exhausted` is what makes the refusal terminal — `--next` has no memory and
+  # would keep offering this branch until the loop's own break fired. It should
+  # not be offering it at all (the scan reads `waiting`), so this arm is the
+  # belt to the preflight's brace: a branch offered by a scan that could not
+  # reach the host still stops here, and it is NOT counted again — the preflight
+  # already reported it.
+  if is_waits_held "$branch"; then
+    exhausted+=("$branch")
+    continue
+  fi
+
+  # BEFORE anything is handed over. The candidate is not yet work in flight —
+  # dispatch creates no desk and pushes no claim — so this describes what stood
+  # before this run rather than what this run made.
   in_flight=$(report_in_flight "$branch")
 
-  # Adopt an existing worktree rather than duplicating it.
-  if git worktree list --porcelain | grep -qx "worktree $wt"; then
-    echo "reusing existing worktree for $branch → $wt"
-    [ -n "$in_flight" ] && printf '%s\n' "$in_flight"
-    n_reused=$((n_reused + 1))
+  # THE BRIEF GATE, AT THE HAND-OVER RATHER THAN AT THE LAUNCH.
+  #
+  # ITS RULE IS UNCHANGED — a slice with no brief is not handed over — AND ONLY
+  # ITS POSITION MOVED. It used to sit between a prepared desk and a started
+  # worker, so a missing brief left a worktree and a claim nobody was sat at:
+  # correct at the time, because preparing was the only thing dispatch could do
+  # first. Dispatch now prepares nothing, so a refused slice leaves nothing at
+  # all and simply stays in the queue.
+  #
+  # THE REFUSAL STILL NAMES THE REF IT LOOKED AT, not a bare path. A brief
+  # sitting unpushed in the operator's checkout is the likeliest reason to see
+  # this message, and `no brief at .plot/briefs/x.md` would send them to look at
+  # a file that is right there — the ref says where the AGENT will look.
+  #
+  # `--no-brief` KEEPS ITS MEANING: it hands over without one and SAYS SO, so
+  # the override stays on the record rather than being silent.
+  if brief_present "$branch"; then
+    # A brief that is present is never refused for age — see
+    # `brief_staleness_note`. The note is printed before the hand-over so it
+    # sits with the branch it describes, and the hand-over happens either way.
+    brief_staleness_note "$branch"
+  elif [ "$no_brief" = 1 ]; then
+    echo "    no brief at $(brief_ref "$branch") — handing it over anyway (--no-brief)"
   else
-    git worktree add -q -b "$branch" "$wt" "origin/$MAIN" 2>/dev/null || {
-      # Branch exists locally already: attach the worktree to it instead.
-      git worktree add -q "$wt" "$branch" 2>/dev/null || {
-        echo "skipped $branch (cannot create worktree)"
-        n_skipped=$((n_skipped + 1))
-        exhausted+=("$branch")
-        continue
-      }
-    }
-    # THE CLAIM. Rejection means another session won the race; leave its
-    # worktree alone and move on to the next branch.
-    #
-    # The claim carries an EMPTY COMMIT, and that is load-bearing. Pushing a
-    # branch that merely points at origin/<main> is a no-op: the remote already
-    # has that commit, so the push succeeds with "Everything up-to-date" and
-    # BOTH dispatchers believe they own the branch. Mutual exclusion requires
-    # the refs to diverge — two independent claim commits are not fast-forwards
-    # of each other, so the second push is rejected as non-fast-forward.
-    #
-    # Never add --force or --force-with-lease here: forcing is precisely what
-    # would let a second dispatcher take a branch someone is working on.
-    git -C "$wt" -c "user.name=${PLOT_CLAIM_WHO:-$(git config user.name || echo plot)}" \
-        commit -q --allow-empty -m "plot: claim $branch" 2>/dev/null
-    if git -C "$wt" push -q -u origin "$branch" 2>/dev/null; then
-      echo "dispatched $branch → $wt"
-      # Reported AFTER the claim, never before: a branch another dispatcher won
-      # is not this run's to describe. The facts themselves were read before the
-      # worktree existed, so the claim cannot have polluted them.
-      [ -n "$in_flight" ] && printf '%s\n' "$in_flight"
-      n_dispatched=$((n_dispatched + 1))
-      # AFTER the claim push, never before. A Started: record for a branch
-      # another dispatcher won would be a lie in the file, and the claim is the
-      # only thing that decides who holds a branch.
-      claimed_now+=("$branch")
-    else
-      echo "skipped $branch (claimed by another session)"
-      git worktree remove --force "$wt" 2>/dev/null || true
-      n_skipped=$((n_skipped + 1))
-      exhausted+=("$branch")
-      continue
-    fi
+    echo "    not handed over — no brief at $(brief_ref "$branch")"
+    echo "      write one: /plot-implement $slug   (then push it, or pass --no-brief to hand it over without one)"
+    # AND NOW SOMETHING IS DONE ABOUT IT. The refusal above stands unchanged;
+    # this line says what happened NEXT. Either arm names itself, so the log
+    # always records which one ran.
+    request_brief "$branch" "$slug" && n_brief_asked=$((n_brief_asked + 1))
+    n_skipped=$((n_skipped + 1))
+    # `exhausted` is what makes the refusal terminal — `--next` has no memory
+    # and would keep offering this branch until the loop's own break fired.
+    exhausted+=("$branch")
+    continue
   fi
 
-  if [ "$no_start" = 0 ]; then
-    # THE BRIEF GATE, between preparing and starting. Prepared work above stands;
-    # only the launch is conditional. A missing brief refuses, naming the file
-    # and the two ways forward — write it, or pass --no-brief. --no-brief starts
-    # anyway and SAYS SO, so the override is on the record rather than silent.
-    #
-    # The refusal names the REF it looked at, not a bare path. A brief sitting
-    # unpushed in the operator's checkout is the likeliest reason to see this
-    # message, and "no brief at .plot/briefs/x.md" would send them to look at a
-    # file that is right there — the ref says where the WORKER will look.
-    if brief_present "$branch"; then
-      start_worker "$branch" "$wt" && n_started=$((n_started + 1))
-    elif [ "$no_brief" = 1 ]; then
-      echo "    no brief at $(brief_ref "$branch") — starting anyway (--no-brief)"
-      start_worker "$branch" "$wt" && n_started=$((n_started + 1))
-    else
-      echo "    prepared, not started — no brief at $(brief_ref "$branch")"
-      echo "      write one: /plot-implement $slug   (then push it, or pass --no-brief to start without it)"
-    fi
-  fi
+  # THE HAND-OVER, AND IT IS THE WHOLE OF WHAT DISPATCH DOES WITH A SLICE.
+  #
+  # `git worktree add` USED TO BE HERE, with a claim push behind it and a worker
+  # start behind that. All three are gone, and each for its own reason:
+  #
+  #   THE DESK. `DESIGN-agent.md:65` — *"agent ──owns──► a worktree (its desk,
+  #   while it lives)"*. One desk per agent, not one per slice. The agent decides
+  #   create-or-reset when it takes the brief, because it is the only party that
+  #   can see its own tree; a desk cut here would be cut before anybody knows
+  #   which agent will sit at it. Measured 2026-09-02: 2 manifests against 11
+  #   worktrees, 5 of them on branches that had already merged.
+  #
+  #   THE CLAIM. A pushed claim makes the branch read `claimed` rather than
+  #   `open`, and the queue is DERIVED — an eligible slice with a brief and no
+  #   claim IS queued. Claiming here would take the slice straight back out of
+  #   the queue it was being put into.
+  #
+  #   THE WORKER. `DESIGN-agent.md:157` — *"nothing starts a worker"*. The
+  #   registry spawns an agent, and spawning it IS starting its process. This
+  #   script hands work to the fleet; it does not staff it.
+  #
+  # SO THE HAND-OVER IS A REPORT AND NOT A WRITE. The queue derives from the
+  # plan, the briefs and the refs, all of which are already on the host, so
+  # there is nothing for this line to store — which is what keeps the daemon
+  # stateless across restarts.
+  #
+  # IT REFUSES NOTHING FOR WANT OF A FREE AGENT, and never asks. An earlier
+  # draft of the plan proposed refusing on `0 free` and it is wrong: it makes
+  # dispatch synchronous with fleet capacity, the coupling `DESIGN-machine.md`
+  # §10 spent two revisions rejecting, and `DESIGN-agent.md:173` states it from
+  # the other side — *"a dispatch never asks the machine for capacity"*. **The
+  # queue absorbs the timing.** A queue longer than the pool is the normal case.
+  echo "handed over $branch → the registry"
+  [ -n "$in_flight" ] && printf '%s\n' "$in_flight"
+  n_dispatched=$((n_dispatched + 1))
+  # AFTER the hand-over rather than after a claim. A `Started:` record now
+  # states that the slice was handed to the fleet, which is what this run did;
+  # who takes it is the registry's to decide and its own to record.
+  claimed_now+=("$branch")
+
 done
 
 # Book AFTER the fan-out, in one commit, so a booking that fails cannot leave