@plot-pm/board 0.16.2 → 0.17.0

package/plot-dispatch.sh

@@ -36,8 +36,8 @@
 #               PR (open or merged), a host it cannot ask, a live worker (named
 #               by pid), real work (a file-changing commit on origin/<br>, or
 #               unpushed commits or uncommitted changes on the local desk), and
-#               a PLOT-BLOCKED marker. A refusal writes nothing. The desk is
-#               never touched.
+#               a PLOT-BLOCKED marker. A refusal writes nothing. A clean,
+#               claim-only desk left on <br> is detached at origin/<main>.
 #   --migrate   move legacy worktrees into the configured `Worktree root:`. An
 #               idle worktree (no live worker, no unlanded work) is moved; a
 #               busy one is skipped with the reason. Requires a `Worktree root:`
@@ -187,6 +187,12 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck source=plot-worker-state.sh
 . "$script_dir/plot-worker-state.sh"
 
+# `desk_dirt` — the reaper's reading of what counts as work on a desk's floor.
+# `--release` asks it before it detaches a desk, so the reaper and the release
+# read one tree the same way. Sourced; it defines one function on load.
+# shellcheck source=plot-desk-dirt.sh
+. "$script_dir/plot-desk-dirt.sh"
+
 # The controller receipt, for `spend_action_receipt` below. Sourced from the
 # ONE file that holds both receipt kinds, for the reason that file states: the
 # gate and the owners must agree on where a receipt lives.
@@ -253,6 +259,21 @@ resolve_wt_root() { # sets globals wt_root, wt_prefix; exits 3 when unaskable
   wt_prefix=""
 }
 
+# WHICH DESK HOLDS A BRANCH, ASKED OF GIT — never rebuilt from the branch name,
+# the rule every verb here follows. `--stop`, `--restart`, `--release` and the
+# held-branch gate each carried a byte-identical copy of this awk, so they now
+# share one and cannot drift.
+#
+# `git worktree list --porcelain` emits `worktree <path>` then `branch
+# refs/heads/<name>` per entry, so the branch line is matched and the path
+# remembered from the preceding line. A detached worktree has no branch line
+# and never matches, which is right: it holds no branch to hold.
+worktree_holding_branch() { # $1=branch → the first desk holding it, or nothing
+  git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$1" '
+    /^worktree /  { path = substr($0, 10) }
+    /^branch /    { if (substr($0, 8) == want) { print path; exit } }'
+}
+
 dry_run=0
 show_monitors=0
 no_start=0
@@ -785,8 +806,12 @@ request_brief() { # $1 = branch, $2 = slug → 0 if a command was started
   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.
+  # on a `claude -p` session of unknown length. `set -m` gives the brief the
+  # process group `setsid` would give: the backgrounded list becomes a job, the
+  # job leads its own group, and `exec` keeps that pid, so a signal to the
+  # dispatcher's group does not reach the brief. `setsid` is not used — it does
+  # not exist on macOS, where most of this fleet runs. `set -m` goes in this bash
+  # subshell and never in the `sh -c` body: dash refuses it without a terminal.
   # THE SETTINGS FILE THIS PROJECT STARTS ITS AGENTS WITH. The `Brief command` is
   # a `claude -p` session like any other agent and inherits every `SessionStart`
   # hook the operator's plugins declare, so it carries the same variable the
@@ -798,12 +823,12 @@ request_brief() { # $1 = branch, $2 = slug → 0 if a command was started
   # which `${VAR:+…}` reads as nothing — so a broken config cannot stop a brief
   # being written.
   _brief_settings="$(bash "$(dirname "${BASH_SOURCE[0]}")/plot-agent-settings.sh" 2>/dev/null || echo "")"
-  ( cd "$repo_root" \
+  ( set -m; cd "$repo_root" \
     && PLOT_UNATTENDED=1 PLOT_PLAN_SLUG="$bslug" PLOT_BRIEF_BRANCH="$branch" \
        PLOT_AGENT_SETTINGS="$_brief_settings" \
-       nohup sh -c "$cmd \"\$@\"" plot-brief \
+       exec nohup sh -c "$cmd \"\$@\"" plot-brief \
        "$(brief_prompt "$branch" "$bslug")" \
-       >"$log" 2>&1 </dev/null & ) 2>/dev/null
+       >"$log" 2>&1 </dev/null & ) >/dev/null 2>&1 </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
@@ -1280,11 +1305,17 @@ start_worker() {
   # 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.)
+  # THE LAUNCH NOW ENDS IN `exec`, so the forked bash IS the wrapper: `$$`
+  # inside the `sh -c` and the pid bash forked name one process, and no process
+  # carrying the dispatcher's command line survives the launch. The wrapper
+  # reparents to init — measured 2026-10-01, its PPID is 1.
+  #
+  # `exec` is also what gives the caller its streams back. The outer subshell
+  # inherited the dispatcher's stdout, and the inner redirect applies to the
+  # backgrounded job alone, so a reader on a pipe waited for an EOF the forked
+  # bash held for as long as the agent lived: measured 2026-10-01, `--start 1`
+  # took 20.39 s through `| cat` against 1.12 s with `exec`. The subshell is
+  # redirected too, because `exec` alone leaves the wrapper holding that pipe.
   #
   # 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
@@ -1343,12 +1374,12 @@ start_worker() {
   #
   # 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.
+  # The AgentMonitor starts INSIDE the wrapper, as its child, immediately
+  # before the agent, watching the desk. The PROCESS is no longer a monitor's
+  # subject: since `bug/the-loop-reports-idle` the loop's own watcher judges `idle`
+  # (`board/plot-worker-loop.mjs`'s `idleVerdict`, built from the domain's
+  # `idleNow`), and the wrapper itself reports `gone`/`clear` after
+  # `wait "$agent"` returns, below.
   #
   # 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
@@ -1374,8 +1405,8 @@ start_worker() {
   # 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*.
+  # into a finding of their own, 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
@@ -1448,15 +1479,8 @@ start_worker() {
     fi
   fi
 
-  local worker_monitor='' agent_monitor='' build_monitor=''
-  [ -x "$script_dir/plot-worker-monitor.sh" ] && worker_monitor="$script_dir/plot-worker-monitor.sh"
+  local agent_monitor=''
   [ -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)
   # THE THREE NAMES THE CHARTER DECLARED, and they travel as env vars for the
@@ -1469,7 +1493,44 @@ start_worker() {
   # byte-identical to what it was — which is the 100% case, since zero charters
   # exist. `PLOT_AGENT` is forwarded too, so the loop's own `resolve_prompt_file`
   # asks about the same agent this launch resolved.
-  ( cd "$wt" && \
+  #
+  # `set -m` FIRST: THE AGENT LEADS ITS OWN PROCESS GROUP. With job control on,
+  # the backgrounded list below is a job, the job gets a group of its own, and
+  # `exec` keeps the job's pid, so the wrapper's pid IS its group id. A SIGKILL
+  # to the starter's group — `killGroup` in `run-script.ts` — then misses the
+  # agent, and `--stop` on one agent ends that wrapper's group and no sibling's.
+  # It goes in this bash subshell and never in the `sh -c` body: dash refuses
+  # `set -m` without a terminal.
+  #
+  # THE WRAPPER IGNORES SIGTERM, AND ONLY AFTER ITS CHILDREN EXIST. `--stop`
+  # signals this whole group, and the wrapper must outlive the agent to write
+  # `.plot-worker.exit` (`test/e2e/monitors-attached.test.mjs`). `trap "" TERM`
+  # comes after `agent=$!`, because an ignored signal is inherited by every child
+  # started after it: set earlier, the monitors and the agent would ignore the
+  # stop too. The wrapper then records the exit code and ends on its own.
+  #
+  # THE WRAPPER ALSO REPORTS `gone`/`clear` ITSELF, right after `wait "$agent"`
+  # returns inside the `sh -c` body below. It already knows the instant the
+  # agent ends, because it `wait`s on it — the same fact `workerAlive` reads in
+  # `rules/supervision.ts`. A non-zero exit (124, 137 for SIGKILL, anything
+  # else) appends `gone`; exit 0 appends `clear`, so a finished agent asks for
+  # no restart and no earlier `idle` stays the newest line. The appended line
+  # matches `publish()`'s own shape exactly (`monitor`, `branch`, `worktree`,
+  # `finding`, `since`, `evidence`, `measuredAt`, `monitor: "WorkerMonitor"`),
+  # so the board's reader cannot tell the difference. This replaces the
+  # WorkerMonitor process `bug/the-loop-reports-idle` removed — which published
+  # `gone` on ANY death of the watched pid, including an honest exit 0, where
+  # this reports `clear` instead.
+  #
+  # THE LINE LANDS IN THE WATCHED DESK, ASKED ONCE, RIGHT AFTER `wait "$agent"`
+  # RETURNS. `PLOT_WORKTREE` is fixed at launch, but a hop rewrites the
+  # manifest's `worktree` field before the agent exits — so the wrapper sources
+  # `plot-monitor-subject.sh` off `$PATH` (set further down, before the agent
+  # starts) and asks `plot_watched_desk` for the desk to write into, exactly
+  # once. Reading it once here, rather than threading `PLOT_WORKTREE` through
+  # the publish, is what keeps a killed hopped agent's `gone` line landing where
+  # the loop's watcher (and the board's reader) actually look.
+  ( set -m; cd "$wt" && \
       # AN `export`, NOT AN ENV PREFIX, AND THE REASON IS A MEASUREMENT. Bash
       # recognises an assignment prefix BEFORE it expands parameters, so a
       # `${caps:+PLOT_CAPABILITIES="$caps"}` in the prefix below is not an
@@ -1493,13 +1554,11 @@ start_worker() {
       PLOT_EFFORT="$launch_effort" \
       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" \
       PLOT_WRAPPER_PID_FILE="$wt/.plot-worker.wrapper.pid" \
       PLOT_SCRIPT_DIR="$script_dir" \
-      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; PATH="$PLOT_SCRIPT_DIR:$PATH"; export PATH; ( '"$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" '"'"'
+      exec nohup sh -c 'printf "%s" "$$" > "$PLOT_WRAPPER_PID_FILE"; wmon=""; amon=""; if [ -n "$PLOT_AGENT_MONITOR" ]; then "$PLOT_AGENT_MONITOR" & amon=$!; fi; PATH="$PLOT_SCRIPT_DIR:$PATH"; export PATH; ( '"$cmd"' ) & agent=$!; trap "" TERM; 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" '"'"'
         BEGIN { relaunch = 0; count = 1; stamped = 0 }
         FNR == NR {
           if ($0 ~ /^  "pid": "[^"]*",$/) {
@@ -1517,7 +1576,6 @@ start_worker() {
           print "  \"wrapperPid\": \"" wrapper "\","
           print "  \"workerMonitorPid\": \"" wmon "\","
           print "  \"agentMonitorPid\": \"" amon "\","
-          print "  \"buildMonitorPid\": \"" bmon "\","
           if (relaunch) {
             print "  \"previousPid\": \"" displaced "\","
             print "  \"relaunches\": " count ","
@@ -1527,13 +1585,12 @@ start_worker() {
         $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 & )
+      '"'"' "$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=$?; wd="$PLOT_WORKTREE"; . plot-monitor-subject.sh 2>/dev/null && wd=$(plot_watched_desk "$PLOT_MANIFEST_FILE" "$PLOT_WORKTREE"); wf="$wd/.plot-worker.monitor.worker.jsonl"; if [ -n "$wd" ]; then now=$(date -u +%Y-%m-%dT%H:%M:%SZ); if [ "$rc" -ne 0 ]; then f=gone; e="the agent pid $agent exited $rc; the wrapper that started it is unattended"; else f=clear; e="the agent pid $agent exited 0; the worker is finished"; fi; printf "{\"monitor\":\"WorkerMonitor\",\"branch\":\"%s\",\"worktree\":\"%s\",\"finding\":\"%s\",\"since\":\"%s\",\"evidence\":\"%s\",\"measuredAt\":\"%s\"}\n" "$PLOT_BRANCH" "$wd" "$f" "$now" "$e" "$now" >> "$wf" 2>/dev/null; fi; printf "%s" "$rc" > "$PLOT_EXIT_FILE"' \
+      >"$log" 2>&1 </dev/null & ) >/dev/null 2>&1 </dev/null
   echo "    started worker (log: $log)"
   return 0
 }
@@ -1763,9 +1820,7 @@ if [ "$mode" = "stop" ]; then
   # A refusal that is confidently wrong is worse than one that is terse, so the
   # path-guess survives only as the LAST candidate and the refusal below says
   # which places were looked in.
-  wt=$(git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$stop_branch" '
-    /^worktree /  { path = substr($0, 10) }
-    /^branch /    { if (substr($0, 8) == want) { print path; exit } }')
+  wt=$(worktree_holding_branch "$stop_branch")
   wt_guess="$wt_root_early/$wt_prefix_early$(printf '%s' "$stop_branch" | tr '/' '-')"
   [ -n "$wt" ] && [ -d "$wt" ] || wt="$wt_guess"
   if [ ! -d "$wt" ]; then
@@ -1783,10 +1838,14 @@ if [ "$mode" = "stop" ]; then
       # THE WHOLE PROCESS GROUP, NOT ONE PID. Measured 2026-09-30 (#1084):
       # `--stop` signalled the wrapper, the group leader, and the loop, the
       # prompt shell, `claude` and its children survived reparented to pid 1;
-      # `kill -TERM -<pgid>` ended all of them. The pid is the fallback when the
-      # group cannot be read, or is this script's own group: a worker started
-      # without job control shares its starter's group, and signalling that
-      # group would stop the caller with it.
+      # `kill -TERM -<pgid>` ended all of them. `start_worker` launches under
+      # `set -m`, so an agent leads its own group and that group holds one
+      # wrapper with its monitors, its loop and its `claude`: the signal ends
+      # this agent and nothing else. An agent started before that change still
+      # shares its starter's group with every sibling the same run started and
+      # with the starter itself. The guard below stays for those agents: the
+      # pid is the target when the group cannot be read, or is this script's
+      # own group, because signalling that group would stop the caller with it.
       stop_pgid=$(ps -o pgid= -p "$pid" 2>/dev/null | tr -d ' ')
       stop_own_pgid=$(ps -o pgid= -p "$$" 2>/dev/null | tr -d ' ')
       stop_target="$pid"
@@ -1847,9 +1906,7 @@ if [ "$mode" = "restart" ]; then
   # wrong. It matters more here than anywhere: the population this verb serves
   # includes the worktree a person made by hand after the tool had no verb for
   # them, and a hand-made worktree rarely follows dispatch's naming.
-  restart_wt=$(git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$restart_branch" '
-    /^worktree /  { path = substr($0, 10) }
-    /^branch /    { if (substr($0, 8) == want) { print path; exit } }')
+  restart_wt=$(worktree_holding_branch "$restart_branch")
   if [ -z "$restart_wt" ] || [ ! -d "$restart_wt" ]; then
     echo "plot-dispatch: no worktree holds '$restart_branch' — nothing to restart." >&2
     echo "  --restart hands an EXISTING checkout to a new worker; it creates none." >&2
@@ -1893,7 +1950,11 @@ if [ "$mode" = "restart" ]; then
   # resets or stashes: a restart that discards that is worse than the missing
   # affordance, because it looks like a supported operation. The new worker's
   # brief already tells it to commit and push before verifying.
-  if [ -n "$(git -C "$restart_wt" status --porcelain </dev/null 2>/dev/null)" ]; then
+  # A REBUILT BUNDLE ALONE IS NOT "UNCOMMITTED WORK". `main` rebuilds and
+  # pushes every generated board bundle (`bug/main-builds-its-bundles`, #1249),
+  # so a desk that locally rebuilt one to test says nothing an agent left on
+  # the floor — excused path by path, same reading `desk_dirt` applies.
+  if [ -n "$(git -C "$restart_wt" status --porcelain </dev/null 2>/dev/null | exclude_bundle_paths "$restart_wt")" ]; then
     echo "  uncommitted work in the tree is kept — the new worker inherits it"
   fi
 
@@ -2001,35 +2062,49 @@ if [ "$mode" = "release" ]; then
   # THE DESK, ASKED OF GIT — never rebuilt from the branch name, the rule every
   # other verb here follows. A manifest naming this branch may name a desk git
   # does not list (removed by hand), so its `worktree` is the fallback.
-  release_wt=$(git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$br" '
-    /^worktree /  { path = substr($0, 10) }
-    /^branch /    { if (substr($0, 8) == want) { print path; exit } }')
+  release_wt=$(worktree_holding_branch "$br")
   registry_dir=$(agent_registry_dir "$repo_root_early")
   named_manifests=()
   if [ -d "$registry_dir" ]; then
     for m in "$registry_dir"/*.json; do
       [ -f "$m" ] || continue
-      m_branch=$(node -e '
-        try {
-          const m = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
-          process.stdout.write(typeof m.branch === "string" ? m.branch : "");
-        } catch { process.stdout.write(""); }
-      ' "$m" 2>/dev/null)
+      m_branch=$(manifest_string "$m" branch) || m_branch=""
       [ "$m_branch" = "$br" ] || continue
       named_manifests+=("$m")
       if [ -z "$release_wt" ]; then
-        m_wt=$(node -e '
-          try {
-            const m = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
-            process.stdout.write(typeof m.worktree === "string" ? m.worktree : "");
-          } catch { process.stdout.write(""); }
-        ' "$m" 2>/dev/null)
+        m_wt=$(manifest_string "$m" worktree) || m_wt=""
         [ -n "$m_wt" ] && [ -d "$m_wt" ] && release_wt="$m_wt"
       fi
     done
   fi
   [ -n "$release_wt" ] && [ -d "$release_wt" ] || release_wt=""
 
+  # A LIVE AGENT HOLDS THE BRANCH IN A DESK OTHER THAN `release_wt` — asked
+  # through the domain, and asked BEFORE refusal 2 below for the reason that
+  # refusal cannot cover: an agent JUST HANDED the branch has not checked it
+  # out, so `release_wt` is empty and refusal 2's desk-bound check does not
+  # run. This asks each manifest NAMING the branch whether ITS OWN desk is
+  # alive, whatever branch that desk currently holds — `claimAnswer` answers
+  # `held-by-agent` from `holders` alone, so the ref and the commit log are not
+  # needed to ask this question.
+  #
+  # `release_wt` ITSELF IS EXCLUDED FROM `holders`, so this never duplicates
+  # refusal 2's case: a manifest whose own desk IS `release_wt` is the live
+  # worker refusal 2 already names with its pid, and this must not pre-empt it
+  # with a different message for the same desk.
+  #
+  # NOT NUMBERED WITH THE FOUR BELOW: the plan keeps their order and wording
+  # unchanged, and this is the one new refusal, asked through the domain.
+  holder_lines=$(live_holders_of_branch "$registry_dir" "$br" "" "$release_wt")
+  answer=$(claim_answer "$script_dir/board/plot-claim-answer.mjs" unknown "" \
+    "$(printf '%s\n' "$holder_lines" | cut -f1)") || answer=""
+  if [ "$answer" = "held-by-agent" ]; then
+    echo "plot-dispatch: $br is held by a live agent — refusing." >&2
+    printf '%s\n' "$holder_lines" | while IFS=$'\t' read -r h_session h_wt; do echo "  $h_session (desk $h_wt)" >&2; done
+    echo "  Nothing was written." >&2
+    exit 1
+  fi
+
   # 2. A LIVE WORKER — the measurement `--restart` makes, through the shared
   # classifier, never `pgrep` by name. A live pid means somebody is working,
   # and the one case where a claim is not abandoned.
@@ -2133,11 +2208,76 @@ if [ "$mode" = "release" ]; then
   else
     echo "  origin/$br does not exist — only the assignment needed releasing"
   fi
-  if [ -n "$release_wt" ]; then
-    echo "  the desk at $release_wt still holds $br and is left as it is"
-  fi
+  # THE DESK THAT STILL HOLDS THE BRANCH IS DETACHED. Measured 2026-10-02: a
+  # released desk kept `$br` with only its empty claim commit. The next agent
+  # handed the slice asked `checkoutYield` whether that checkout yields; with
+  # the remote ref deleted it has no upstream, `unpushedCommits` reads
+  # `unknown`, and the rule keeps it. Fifteen agents in a row wrote
+  # PLOT-BLOCKED for two released slices between 13:46 and 14:59.
+  #
+  # Detaching at origin/<main> is the state a free agent's desk already has, so
+  # the desk stays usable and the branch is free for the next checkout. The
+  # worktree itself stays: removing it is the reaper's licence, not this one.
+  #
+  # FOUR READINGS, each asked again rather than inferred from the refusals
+  # above, so a change to those refusals cannot silently widen this write:
+  #   - the desk's HEAD is `refs/heads/$br` (a manifest's `worktree` may name a
+  #     desk on another branch);
+  #   - no live worker, through the shared classifier;
+  #   - no file-changing commit beyond origin/<main> — the count step 3 takes,
+  #     with origin/<main> as the base because the claim ref is now gone;
+  #   - a clean tree by `desk_dirt`, the reaper's reading.
+  # Any reading that fails keeps today's behaviour and names the reason.
+  detached_desks=0
+  release_holders=$(git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$br" '
+    /^worktree /  { path = substr($0, 10) }
+    /^branch /    { if (substr($0, 8) == want) print path }')
+  [ -z "$release_holders" ] && [ -n "$release_wt" ] && release_holders="$release_wt"
+  while IFS= read -r desk; do
+    [ -n "$desk" ] || continue
+    keep_reason=""
+    if [ ! -d "$desk" ]; then
+      keep_reason="the directory does not exist"
+    elif [ "$(git -C "$desk" symbolic-ref -q HEAD </dev/null 2>/dev/null)" != "refs/heads/$br" ]; then
+      keep_reason="its HEAD is not refs/heads/$br"
+    else
+      case "$(plot_worker_state "$desk" "" | cut -f1)" in
+        running) keep_reason="a worker is alive in it" ;;
+      esac
+    fi
+    if [ -z "$keep_reason" ]; then
+      desk_work=$(git -C "$desk" rev-list --count "refs/remotes/origin/$MAIN..HEAD" -- . </dev/null 2>/dev/null) || desk_work=""
+      case "$desk_work" in
+        0) ;;
+        ''|*[!0-9]*) keep_reason="its commits beyond origin/$MAIN could not be counted" ;;
+        *) keep_reason="$desk_work commit(s) beyond origin/$MAIN change files" ;;
+      esac
+    fi
+    if [ -z "$keep_reason" ]; then
+      desk_floor=$(desk_dirt "$desk")
+      [ -n "$desk_floor" ] && keep_reason="uncommitted changes: $(printf '%s\n' "$desk_floor" | cut -c4- | tr '\n' ' ')"
+    fi
+    if [ -z "$keep_reason" ]; then
+      if ! git -C "$desk" checkout -q --detach "refs/remotes/origin/$MAIN" </dev/null 2>/dev/null; then
+        keep_reason="git refused to detach it at origin/$MAIN"
+      fi
+    fi
+    if [ -n "$keep_reason" ]; then
+      echo "  the desk at $desk still holds $br and is left as it is: $keep_reason"
+      continue
+    fi
+    detached_desks=$((detached_desks + 1))
+    # Only empty claim commits are lost, and the remote ref is already gone.
+    if git branch -q -D "$br" </dev/null 2>/dev/null; then
+      echo "  detached the desk at $desk at origin/$MAIN and deleted the local branch $br"
+    else
+      echo "  detached the desk at $desk at origin/$MAIN; the local branch $br could not be deleted"
+    fi
+  done <<EOF
+$release_holders
+EOF
   echo "released $br — the slice returns to the queue"
-  echo "summary: released=1 manifests=$released_manifests ref=$([ "$ref_present" = 1 ] && echo deleted || echo absent)"
+  echo "summary: released=1 manifests=$released_manifests ref=$([ "$ref_present" = 1 ] && echo deleted || echo absent) detached=$detached_desks"
   exit 0
 fi
 
@@ -2892,7 +3032,9 @@ esac
 # 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
+# has never seen a PR for that branch. For a name in `plot-fleet-scan.sh
+# --slice-names` — a slice of any live plan, not deferred — that is a slice
+# nobody started, which is `waiting`; for any other name it 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.
 
@@ -2926,13 +3068,20 @@ prereq_answer() { # $1=prerequisite branch → merged|unmerged|none|unreachable
 }
 
 # 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`.
+# the same blob, in the plan's own order, one line of `branch<TAB>prerequisite`
+# PER PREREQUISITE: a branch naming two prints two lines, in the plan's order.
+#
+# `waits_on` IS A LIST (`["bug/a","bug/b"]`), never the one-name string this
+# used to match. The old `"waits_on":"[^"]*"` pattern does not match an array,
+# so an unmigrated reader here would read every slice as waiting on nothing and
+# dispatch a held slice — the defect this plan exists to remove, reintroduced
+# by the parser's own fix had this not moved with it (#1153).
 #
 # 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
+waits_pairs() { # → branch<TAB>prerequisite, one line per prerequisite
   printf '%s' "$gate_meta" | awk '
     {
       n = split($0, parts, /\{"branch":"/)
@@ -2940,9 +3089,11 @@ waits_pairs() { # → branch<TAB>prerequisite, one per annotated branch
         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
+        if (match(rec, /"waits_on":\[[^]]*\]/)) {
+          list = substr(rec, RSTART + 12, RLENGTH - 13)
+          gsub(/"/, "", list)
+          m = split(list, names, ",")
+          for (j = 1; j <= m; j++) if (names[j] != "") print br "\t" names[j]
         }
       }
     }'
@@ -2995,12 +3146,9 @@ is_waits_held() {
 # 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.
+# The array is read directly as `${waits_freed[@]}`; the predicate wrapper
+# `is_waits_held` has beside it was never called and is gone.
 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`.
@@ -3015,22 +3163,45 @@ is_waits_freed() {
 # 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
+  local br prereq answer held slice_names=""
   while IFS=$'\t' read -r br prereq; do
     [ -n "$br" ] || continue
     answer=$(prereq_answer "$prereq")
     case "$answer" in
       merged) continue ;;
-      none)   held=blocked ;;
+      # A slice somebody may still start has no PR until its work starts: a
+      # wait, not a typo (#1305). The set is the scan's, of the whole estate,
+      # so a slice of ANOTHER plan reads as it does on the board. Asked once,
+      # and only when the host answered `none`.
+      # ABSENT IS NOT FALSE. A scan that failed or printed nothing leaves the
+      # set unread, and an unread set holds the branch at `waiting` exactly as
+      # an unaskable host does: telling an operator to fix a correct plan is its
+      # own defect. stderr stays visible, and the refusal names the failure.
+      none)   [ -n "$slice_names" ] || slice_names=$'\n'"$("$script_dir/plot-fleet-scan.sh" --slice-names)"$'\n' || slice_names=$'\n\n'
+              case "$slice_names" in
+                $'\n\n') held=waiting
+                          echo "plot-fleet-scan.sh --slice-names gave no answer: $prereq has no PR, held as waiting rather than called a typo" ;;
+                *$'\n'"$prereq"$'\n'*) held=waiting ;;
+                *) held=blocked ;;
+              esac ;;
       *)      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.
+    # `--allow-waiting` SAYS SO ON THE LINE IT OVERRIDES, ONCE PER PREREQUISITE
+    # — an override nobody can see in the output is an override nobody can
+    # audit, and a branch with two unmerged prerequisites names both so the
+    # audit trail is complete.
     if [ "$allow_waiting" = 1 ]; then
       echo "$br waits on $prereq ($held) — dispatching anyway (--allow-waiting)"
       waits_freed+=("$br")
       continue
     fi
+    # ONE REFUSAL PER BRANCH, NOT PER PREREQUISITE. `waits_pairs` prints one
+    # line per unmerged prerequisite in the plan's order, so a branch with
+    # `[merged, unmerged]` reaches this loop once — but `[unmerged, unmerged]`
+    # would reach it twice, and a branch already held names only the FIRST
+    # prerequisite that held it: `is_waits_held` guards both the second refusal
+    # line and the double-count in `n_skipped`.
+    if is_waits_held "$br"; then continue; fi
     waits_held+=("$br")
     n_skipped=$((n_skipped + 1))
     if [ "$held" = "blocked" ]; then
@@ -3101,9 +3272,7 @@ worker_state_field() {
 #
 # `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
-  echo "summary: dispatched=$1 reused=$2 skipped=$3 started=$4 brief=missing worker=$(worker_state_field) brief_asked=${n_brief_asked:-0}"
-}
+# The line is printed once, at the end of the run.
 
 # ---------------------------------------------------------------------------
 # Parallel-agents cap: warn and raise when exceeded
@@ -3135,21 +3304,6 @@ read_parallel_agents_cap() {
   [ -n "$cap" ] && echo "$cap" || echo 3
 }
 
-# Count workers in live states (running or waiting) across all fleet worktrees.
-# These are the slots that count against the cap.
-count_live_workers() {
-  local n=0 wt br st
-  for wt in "$wt_root"/"$wt_prefix"*; do
-    [ -d "$wt" ] || continue
-    br=$(git -C "$wt" branch --show-current 2>/dev/null || echo "?")
-    st=$(worker_state "$wt" "$br")
-    case "$st" in
-      running*|waiting*) n=$((n + 1)) ;;
-    esac
-  done
-  echo "$n"
-}
-
 # Get the branches currently occupying slots (for the warning message).
 live_worker_branches() {
   local wt br st
@@ -3163,6 +3317,13 @@ live_worker_branches() {
   done
 }
 
+# Count workers in live states (running or waiting) across all fleet worktrees.
+# These are the slots that count against the cap — the branches above, counted,
+# so the two readings cannot disagree about what occupies a slot.
+count_live_workers() {
+  live_worker_branches | grep -c . || true
+}
+
 # Update the parallel-agents cap in the fleet controls file.
 # Creates the file (and directory) if needed, preserving autoDispatch if present.
 update_parallel_agents_cap() { # $1 = new cap
@@ -3512,10 +3673,22 @@ committed_files() { # $1=branch → paths, one per line
 
 # Files a branch holds only in its worktree — no ref carries these, so they are
 # invisible to every ref-based check including this script's own.
+#
+# A REBUILT BUNDLE IS EXCLUDED, path by path, same as `desk_dirt`: `main`
+# rebuilds and pushes every generated board bundle
+# (`bug/main-builds-its-bundles`, #1249), so it is never a branch's own
+# uncommitted work. The held-worktree gate below reads this list to decide
+# whether a worktree counts as held, and a rebuilt-but-unchanged bundle must
+# not be the reason a free worktree reads occupied.
 uncommitted_files() { # $1=worktree → paths, one per line
-  local wt="$1"
+  local wt="$1" bundles
   [ -d "$wt" ] || return 0
-  git -C "$wt" status --porcelain </dev/null 2>/dev/null | awk '
+  bundles=$(bundle_paths "$wt")
+  git -C "$wt" status --porcelain </dev/null 2>/dev/null | awk -v bundles="$bundles" '
+    BEGIN {
+      n = split(bundles, arr, "\n")
+      for (i = 1; i <= n; i++) if (arr[i] != "") excluded[arr[i]] = 1
+    }
     {
       # Porcelain v1: XY then a space then the path. A rename prints
       # "old -> new"; the new path is the one on disk.
@@ -3523,7 +3696,7 @@ uncommitted_files() { # $1=worktree → paths, one per line
       i = index(line, " -> ")
       if (i > 0) line = substr(line, i + 4)
       gsub(/^"|"$/, "", line)
-      if (line != "") print line
+      if (line != "" && !(line in excluded)) print line
     }'
 }
 
@@ -3631,9 +3804,7 @@ held_worktree() { # $1=branch → prints the worktree path when held, else nothi
   # refs/heads/<name>` per entry, so the branch line is matched and the path
   # remembered from the preceding line. A detached worktree has no branch line
   # and never matches, which is right: it holds no branch to hold.
-  wt=$(git worktree list --porcelain </dev/null 2>/dev/null | awk -v want="refs/heads/$br" '
-    /^worktree /  { path = substr($0, 10) }
-    /^branch /    { if (substr($0, 8) == want) { print path; exit } }')
+  wt=$(worktree_holding_branch "$br")
   [ -n "$wt" ] || return 1
   # A registered worktree whose directory is gone (removed by hand, not via
   # `git worktree remove`) holds nobody. `status` cannot be read there anyway.
@@ -3775,7 +3946,11 @@ IN_FLIGHT_MAX_BRANCHES=8
 report_monitors() { # $1=worktree
   [ "$show_monitors" = 1 ] || return 0
   local wt="$1" m
-  for m in worker agent; do
+  # ONLY `agent` IS A SCRIPT ANY MORE. `bug/the-loop-reports-idle` removed
+  # `plot-worker-monitor.sh`: the PROCESS no longer has a monitor to report —
+  # the loop's own watcher judges `idle` and the wrapper itself reports
+  # `gone`/`clear`, neither of which this dry run can name as a script path.
+  for m in agent; do
     local script="$script_dir/plot-$m-monitor.sh"
     if [ -x "$script" ]; then
       echo "  would attach: $script → $wt"
@@ -4053,7 +4228,7 @@ book_started ${claimed_now[@]+"${claimed_now[@]}"} || true
 # appears before the footer.
 check_and_update_cap "$n_started"
 
-print_summary "$n_dispatched" "$n_reused" "$n_skipped" "$n_started"
+echo "summary: dispatched=$n_dispatched reused=$n_reused skipped=$n_skipped started=$n_started brief=missing worker=$(worker_state_field) brief_asked=${n_brief_asked:-0}"
 
 # THE RECEIPT IS SPENT HERE, on the fan-out COMPLETING — never at the gate.
 # `plot-controller-gate.sh` clears on a receipt and LEAVES it, so a run that