@plot-pm/board 0.16.1 → 0.16.3

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.
@@ -219,43 +225,55 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # WHERE THE WORKTREES LIVE, and by what name
 # ---------------------------------------------------------------------------
 #
-# Two facts, resolved together because the second is a PROPERTY OF THE FIRST:
-# the root directory the worktrees sit in, and the prefix their directory names
-# carry. `plot-wt-` exists to make Plot's worktrees identifiable AMONG UNRELATED
-# directories — it is a workaround for sharing a parent with other projects.
-# Under a dedicated `Worktree root:` the directory already says what they are,
-# so the prefix answers a question nobody is asking and is dropped. The legacy
-# default keeps it, where it is still doing its job. Two conventions coexist
-# permanently, and that is the intended outcome, not a transition cost.
+# Two facts: the root directory the worktrees sit in, and the prefix their
+# directory names carry. The root is the desk root, `deskRoot`'s answer asked
+# through `plot-desk-root.sh`:
+#
+#   `Worktree root:` absent or empty → <main checkout>/.worktrees
+#   relative value                   → <main checkout>/<value>
+#   absolute value                   → <value> as given
+#
+# The prefix is always empty. `plot-wt-` made Plot's worktrees identifiable
+# among unrelated directories in the checkout's parent; the desk root is a
+# directory Plot owns, so the directory already says what they are. Desks a
+# dispatch created under the old default keep their `plot-wt-` names and their
+# place: every read of "which worktree holds this branch" asks `git worktree
+# list`, and `plot-reap.sh` still recognises the legacy path.
 #
-#   `Worktree root:` absent  → repo_root/.. , prefix `plot-wt-`   (today's behaviour)
-#   relative value           → repo_root/<value> , NO prefix
-#   absolute value           → <value> as given , NO prefix
+# The root is the MAIN checkout's, wherever this runs: inside a desk,
+# `--show-toplevel` answers the desk and `.worktrees` would resolve beneath it.
+# There is NO FALLBACK: when the rule cannot be asked, dispatch stops with the
+# reason rather than compute a second default.
 #
 # THIS FUNCTION ONLY COMPOSES A ROOT AND A PREFIX. It is the CREATION side. Every
 # read of "which worktree holds this branch" asks `git worktree list` instead —
 # see THE HELD-BRANCH GATE. A second naming convention gives path-guessing a
 # second way to be wrong, so path-guessing is confined to creation alone.
-resolve_wt_root() { # $1=repo_root → sets globals wt_root, wt_prefix
-  local rr="$1" configured
-  configured=$("$script_dir/plot-config.sh" get "Worktree root" "")
-  if [ -z "$configured" ]; then
-    # The legacy default: beside the repo, prefixed. No existing checkout moves.
-    wt_root=$(cd "$rr/.." && pwd)
-    wt_prefix="plot-wt-"
-    return
-  fi
-  case "$configured" in
-    /*) wt_root="$configured" ;;                 # absolute: taken as given
-    *)  wt_root="$rr/$configured" ;;             # relative: against the repo root
-  esac
-  # Normalise away a trailing slash so composed paths never double it. The
-  # directory may not exist yet (created on first dispatch), so this is pure
-  # string work, not a `cd`.
-  wt_root="${wt_root%/}"
+# shellcheck source=plot-desk-root.sh
+. "$script_dir/plot-desk-root.sh"
+resolve_wt_root() { # sets globals wt_root, wt_prefix; exits 3 when unaskable
+  wt_root=$(plot_desk_root "$(plot_repo_root)") || {
+    echo "plot-dispatch: cannot resolve where the worktrees go — nothing was dispatched." >&2
+    exit 3
+  }
   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
@@ -788,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
@@ -801,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
@@ -1283,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
@@ -1346,12 +1374,14 @@ 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.
+  # Two monitors start INSIDE the wrapper, as its children, immediately before
+  # the agent: one watches the desk (`plot-agent-monitor.sh`), one watches the
+  # run (`plot-build-monitor.sh`). Each has a subject the other does not and a
+  # cadence it cannot share — minutes on the host, seconds on a run but only
+  # while one is live. The PROCESS is no longer a third monitor's subject:
+  # since `bug/the-loop-reports-idle` the loop's own watcher judges `idle`
+  # (`plot-worker-state.sh`'s `plot_worker_idle_watch_pass`), 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
@@ -1377,8 +1407,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
@@ -1451,8 +1481,7 @@ 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='' build_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
@@ -1472,7 +1501,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
@@ -1496,13 +1562,12 @@ 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=""; bmon=""; 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=$!; 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" -v bmon="$bmon" '"'"'
         BEGIN { relaunch = 0; count = 1; stamped = 0 }
         FNR == NR {
           if ($0 ~ /^  "pid": "[^"]*",$/) {
@@ -1535,8 +1600,8 @@ start_worker() {
         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
 }
@@ -1645,9 +1710,13 @@ charter_file_for() { # $1 = agent name → prints the path it would read
 # inspectable and stoppable even if the plan was since delivered or rejected.
 # Refusing to show a running worker because of a phase change would strand it.
 repo_root_early=$(git rev-parse --show-toplevel)
-resolve_wt_root "$repo_root_early"
-wt_root_early="$wt_root"
-wt_prefix_early="$wt_prefix"
+# Only the two verbs that enumerate desks ask for the root here; every other
+# path asks where it composes one, so its own refusals answer first.
+if [ "$mode" = status ] || [ "$mode" = stop ]; then
+  resolve_wt_root
+  wt_root_early="$wt_root"
+  wt_prefix_early="$wt_prefix"
+fi
 
 # States: "running <pid>" | "finished <pid>" | "waiting <pid> (answer it)"
 #       | "stalled <pid> (work unfinished)" | "failed <pid> (exit N)"
@@ -1762,9 +1831,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
@@ -1782,10 +1849,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"
@@ -1846,9 +1917,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
@@ -1892,7 +1961,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
 
@@ -2000,35 +2073,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.
@@ -2132,11 +2219,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
 
@@ -2160,7 +2312,6 @@ if [ "$mode" = "start" ]; then
   # about any plan, so there is no plan whose phase could refuse it. A gate on a
   # slug this verb never takes would refuse every call.
   repo_root="$repo_root_early"
-  resolve_wt_root "$repo_root"
 
   # THE DEFAULT BRANCH, by the same three steps the fan-out takes below — the
   # config key, then origin's own HEAD, then `main`. Resolved here because the
@@ -2370,6 +2521,9 @@ EOF
   # `wait_for_work` skips the outlook scan for an agent that holds none.
   slug=""
 
+  # Where the desks go, asked only now: every refusal above answers first, and
+  # a broken runtime is named by the start-command check rather than here.
+  resolve_wt_root
   start_made=0
   start_i=0
   while [ "$start_i" -lt "$start_n" ]; do
@@ -2423,6 +2577,9 @@ EOF
       continue
     fi
     mkdir -p "$wt_root" 2>/dev/null || true
+    # The desk root lies inside the repository by default, so keep it out of
+    # `git status` the moment it exists.
+    plot_exclude_desk_root "$(plot_repo_root)"
     if ! git worktree add -q --detach "$start_wt" "origin/$start_main" 2>/dev/null; then
       # NO REMOTE REF IS NOT A FAILURE OF THIS VERB. A fresh clone or a repo
       # with no remote has no `origin/<main>`; the local one is the same commit
@@ -2438,10 +2595,7 @@ EOF
     # the marker is ignored via `info/exclude` rather than `.gitignore`, because
     # an untracked file in a desk reads as unlanded work to
     # `plot-worker-state.sh` and would make every free agent look stalled.
-    _excl="$(git -C "$start_wt" rev-parse --git-common-dir 2>/dev/null)/info/exclude"
-    if [ -f "$_excl" ] && ! grep -qxF '.metadata_never_index' "$_excl" 2>/dev/null; then
-      printf '%s\n' '.metadata_never_index' >> "$_excl" 2>/dev/null || true
-    fi
+    plot_desk_exclude "$start_wt" '.metadata_never_index'
     : > "$start_wt/.metadata_never_index" 2>/dev/null || true
 
     echo "  desk $start_wt (detached at origin/$start_main)"
@@ -2484,8 +2638,9 @@ if [ "$mode" = "migrate" ]; then
   configured_root=$("$script_dir/plot-config.sh" get "Worktree root" "")
   if [ -z "$configured_root" ]; then
     echo "plot-dispatch --migrate: no 'Worktree root:' configured — nothing to migrate."
-    echo "  When Worktree root is absent, worktrees live beside the repo (plot-wt-*)."
-    echo "  To migrate, first add a 'Worktree root:' key to ## Plot Config."
+    echo "  When Worktree root is absent, new worktrees go to <repo>/.worktrees;"
+    echo "  desks an older dispatch made beside the repo (plot-wt-*) stay there."
+    echo "  To move those, first add a 'Worktree root:' key to ## Plot Config."
     exit 0
   fi
 
@@ -2922,13 +3077,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":"/)
@@ -2936,9 +3098,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]
         }
       }
     }'
@@ -2991,12 +3155,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`.
@@ -3020,13 +3181,22 @@ run_waits_preflight() { # → prints refusals; fills waits_held, adds to n_skipp
       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.
+    # `--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
@@ -3042,13 +3212,12 @@ run_waits_preflight() { # → prints refusals; fills waits_held, adds to n_skipp
 }
 
 # 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
-# among unrelated sibling directories). A nested root is made invisible to
-# `git status` and the marker grep by a `.gitignore` line, not by living
-# outside the repo.
+# The default is `<main checkout>/.worktrees` with no prefix; a `Worktree root:`
+# key relocates them. A root inside the repository is kept out of `git status`
+# by the `info/exclude` line `plot_exclude_desk_root` writes when a desk is
+# created.
 repo_root=$(git rev-parse --show-toplevel)
-resolve_wt_root "$repo_root"
+resolve_wt_root
 
 n_dispatched=0 n_reused=0 n_skipped=0 n_started=0
 n_brief_asked=0
@@ -3132,21 +3301,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
@@ -3160,6 +3314,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
@@ -3289,6 +3450,9 @@ write_started_record() { # $@ = branches
   # stale tip and the push would be a guaranteed non-fast-forward.
   git fetch -q origin "$MAIN" 2>/dev/null
 
+  # `git worktree add` creates the desk root when it is missing; exclude it
+  # first so the booking leaves no untracked `.worktrees/` behind.
+  plot_exclude_desk_root "$(plot_repo_root)"
   # -B: a leftover branch from an earlier failed booking must not block this
   # one. It is disposable by construction — created here, pushed, deleted.
   if ! git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null; then
@@ -3506,10 +3670,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.
@@ -3517,7 +3693,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
     }'
 }
 
@@ -3625,9 +3801,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.
@@ -3769,7 +3943,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"