@plot-pm/board 0.16.0 → 0.16.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
     "plot-config.sh",
     "plot-default-branch.sh",
     "plot-deliver.sh",
+    "plot-desk-root.sh",
     "plot-dispatch.sh",
     "plot-fleet-scan.sh",
     "plot-host.sh",

package/plot-approve.sh

@@ -128,7 +128,13 @@ git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository — run thi
 cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
 
 repo_root=$(git rev-parse --show-toplevel)
-wt_root=$(cd "$repo_root/.." && pwd)
+# The booking worktree goes under the desk root of the MAIN checkout, never of
+# this tree: inside a desk `--show-toplevel` answers the desk, and the default
+# `.worktrees` would resolve beneath it. No fallback — `plot-desk-root.sh`.
+# shellcheck source=plot-desk-root.sh
+. "$script_dir/plot-desk-root.sh"
+main_root=$(plot_repo_root)
+wt_root=$(plot_desk_root "$main_root") || die "cannot resolve where the booking worktree goes (see above)"
 
 PLAN_DIR=$(cfg "Plan directory" "docs/plans/")
 ACTIVE_DIR=$(cfg "Active index" "docs/plans/active/")
@@ -735,6 +741,9 @@ else
 
   bookbr="plot/approve-$slug"
   tmpwt="$wt_root/.plot-approve-$slug.$$"
+  # `git worktree add` creates the desk root when it is missing, so exclude it
+  # first: a booking run must not leave `.worktrees/` untracked in `git status`.
+  plot_exclude_desk_root "$main_root"
   # -B: a leftover branch from an earlier failed run must not block this one.
   # It is disposable by construction — created here, pushed, deleted.
   git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null \

package/plot-config.sh

@@ -27,12 +27,7 @@
 #   Project board | Branch prefixes | Plan directory | Active index |
 #   Delivered index | Sprint directory | Story directory | Story index |
 #   Plan template | Worker prompt template | Main branch | Board command
-#   Worktree root       where /plot-dispatch puts its worktrees. Read by
-#                       plot-dispatch.sh; default is the repo's PARENT, which
-#                       scatters `plot-wt-*` beside the checkout. An absolute
-#                       path is taken as given; a relative one resolves against
-#                       the repo root, so `.worktrees` gathers them inside it.
-#                       The default is kept for repos that never set it.
+#   Worktree root       the desk root; see its entry under the agent keys below.
 #   Worker bound        seconds a single prompt run may take in the worker loop
 #                       before it is ended and the worker exits (no hop). Read by
 #                       plot-worker-loop.sh; default 3600 (~1h), `0` disables it.
@@ -99,24 +94,26 @@
 #                       project-owned and reviewed like this one.
 #                       Absent or empty = no change, so an adopting project that
 #                       sets nothing behaves exactly as today.
-#   Worktree root       where /plot-dispatch creates fleet worktrees. A relative
-#                       value resolves against the repo root, an absolute one is
-#                       taken as given. Absent = the default `repo_root/..` with
-#                       the `plot-wt-` prefix — today's behaviour, so no existing
-#                       checkout moves. Under a dedicated root the prefix is
-#                       dropped: the directory already says these are Plot's. Read
-#                       only by the CREATION path; every "which worktree holds this
-#                       branch" read asks `git worktree list` instead.
+#   Worktree root       the desk root: where /plot-dispatch creates fleet
+#                       worktrees and the board writes its action records. A
+#                       relative value resolves against the MAIN checkout, an
+#                       absolute one is taken as given. Absent or empty =
+#                       `<repo>/.worktrees`. The rule is `deskRoot`, asked through
+#                       `plot-desk-root.sh`; no script resolves it itself. Desks
+#                       carry no prefix; `plot-wt-*` desks an older dispatch made
+#                       beside the repo stay there. Every "which worktree holds
+#                       this branch" read asks `git worktree list` instead.
 # Agent-runner keys (optional; Plot hardcodes no agent tooling, Principle 5):
 #   Worker command      how /plot-dispatch runs an agent headless on a worktree.
-#                       `none` = asked, and this repo starts workers by hand —
-#                       a DELIBERATE absence, distinct from a missing key so
-#                       /plot-dispatch stops asking at every fan-out. Never run
-#                       as a command. Absent = nobody has been asked yet, and
-#                       the first dispatch asks (never /plot-init: at adoption
-#                       the question meets a need the answerer does not have,
-#                       gets a shrug, and an answered-and-wrong key is harder
-#                       to fix than a missing one).
+#                       /plot-init writes `PLOT_UNATTENDED=1 plot-worker-loop.sh`;
+#                       the bare name resolves to the loop beside
+#                       plot-dispatch.sh, which puts its own directory first on
+#                       PATH. A free agent (`--start`) refuses a command that
+#                       does not run the loop, because only the loop waits for a
+#                       slice. Absent = not set up: nothing starts, and
+#                       /plot-dispatch offers to write the loop. `none` = asked,
+#                       and this repo starts workers by hand — a DELIBERATE
+#                       absence, never run as a command.
 #   Approve command     how the board runs `/plot-approve <slug>`; the prompt is
 #                       appended as one argument. Absent = the board's Approve
 #                       button renders disabled, naming this key as the fix.

package/plot-deliver.sh

@@ -81,7 +81,13 @@ git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository — run thi
 cfg() { bash "$script_dir/plot-config.sh" get "$1" "$2"; }
 
 repo_root=$(git rev-parse --show-toplevel)
-wt_root=$(cd "$repo_root/.." && pwd)
+# The booking worktree goes under the desk root of the MAIN checkout, never of
+# this tree: inside a desk `--show-toplevel` answers the desk, and the default
+# `.worktrees` would resolve beneath it. No fallback — `plot-desk-root.sh`.
+# shellcheck source=plot-desk-root.sh
+. "$script_dir/plot-desk-root.sh"
+main_root=$(plot_repo_root)
+wt_root=$(plot_desk_root "$main_root") || die "cannot resolve where the booking worktree goes (see above)"
 
 PLAN_DIR=$(cfg "Plan directory" "docs/plans/")
 ACTIVE_DIR=$(cfg "Active index" "docs/plans/active/")
@@ -635,6 +641,9 @@ git fetch -q origin "$MAIN" 2>/dev/null
 
 bookbr="plot/deliver-$slug"
 tmpwt="$wt_root/.plot-deliver-$slug.$$"
+# `git worktree add` creates the desk root when it is missing, so exclude it
+# first: a booking run must not leave `.worktrees/` untracked in `git status`.
+plot_exclude_desk_root "$main_root"
 # -B: a leftover branch from an earlier failed run must not block this one.
 git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null \
   || die "could not prepare a booking worktree at $tmpwt.

package/plot-desk-root.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# The ONE answer to "where do desks and action records go?" — sourced, not run.
+#
+# Every script that resolved this privately asks here instead. Nine sites
+# computed the rule on 2026-10-01 and two of them already answered `.worktrees`
+# while seven answered the checkout's parent, so one of the two populations was
+# always writing somewhere the other did not read.
+#
+# The rule itself is `deskRoot` in the domain, asked through
+# `board/plot-desk-root.mjs`, per *A Shell Script Asks The Domain*: every caller
+# runs once per operator command, which is the cost rule's permitted case.
+#
+# NO CALLER KEEPS A FALLBACK DEFAULT. When the bundle cannot answer — no `node`,
+# a missing file — the caller stops with the reason. A silent fallback is a
+# second default, and two defaults are the defect this removes.
+#
+#   plot_repo_root            → the MAIN checkout, from anywhere
+#   plot_desk_root [repo [configured]] → the desk root; exit 3 when unaskable
+#   plot_exclude_desk_root [repo] → keep it out of `git status`; never fails
+#
+# shellcheck shell=bash
+
+# The MAIN checkout, from a desk as readily as from the checkout itself.
+#
+# `--show-toplevel` answers the DESK inside a linked worktree, so with
+# `.worktrees` as the default it would resolve `<desk>/.worktrees` and place
+# every tree under a root nothing else reads. `plot-reap.sh:440-447` recorded
+# that failure on 2026-09-10, when every tree read as unplaceable.
+#
+# The parent of `--git-common-dir` is the main checkout from anywhere, because
+# every linked worktree shares that one directory. It is asked FIRST and
+# `--show-toplevel` is the fallback, since the common dir is also correct in a
+# non-worktree checkout: there `.git` is a real directory in the root.
+#
+# PHYSICAL, through `pwd -P`: `git worktree list` and `--show-toplevel` print
+# resolved paths, and a desk root composed from a logical one (`/tmp` against
+# `/private/tmp` on macOS) is a prefix no worktree path ever starts with.
+plot_repo_root() {
+  local common root=''
+  common=$(git rev-parse --git-common-dir 2>/dev/null) && [ -n "$common" ] && {
+    common=$(cd -- "$common" 2>/dev/null && pwd -P) || common=''
+    [ -n "$common" ] && root=$(dirname -- "$common")
+  }
+  [ -n "$root" ] || root=$(git rev-parse --show-toplevel 2>/dev/null) || root=$(pwd)
+  printf '%s\n' "$root"
+}
+
+# Resolved ONCE at source time, the way `plot-pr-merged.sh:105` resolves its
+# own bundle. Computing it inside a function reads `BASH_SOURCE[0]` at call
+# time, which is the caller's file once the function has been exported.
+_plot_desk_root_mjs="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/board/plot-desk-root.mjs"
+_plot_desk_root_config="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/plot-config.sh"
+
+# The desk root for a repository, or exit 3 with the reason on stderr.
+#
+# A second argument is a value the caller was handed in place of the key — a
+# `--worktrees DIR` flag — and goes through the same rule; without one the
+# `Worktree root` key is read.
+#
+# READ THE EXIT CODE. A caller that treats an empty answer as a location would
+# compose paths against the filesystem root.
+plot_desk_root() {
+  local repo="${1:-}" bundle="$_plot_desk_root_mjs" configured answer
+  [ -n "$repo" ] || repo=$(plot_repo_root)
+  if [ ! -f "$bundle" ]; then
+    printf 'plot: cannot resolve the desk root: %s is missing\n' "$bundle" >&2
+    return 3
+  fi
+  if [ "$#" -ge 2 ]; then
+    configured="$2"
+  else
+    # Read from the TARGET repository, never the ambient one: `plot-config.sh`
+    # walks up from its cwd, so a caller asking about another checkout would
+    # otherwise get this one's key.
+    # A read that fails is a refusal, never the absent row: reading it as empty
+    # would answer the default for a repository that configured another root.
+    configured=$(cd -- "$repo" 2>/dev/null && bash "$_plot_desk_root_config" get "Worktree root" "" 2>/dev/null) || {
+      printf 'plot: cannot resolve the desk root: the Worktree root key in %s could not be read\n' "$repo" >&2
+      return 3
+    }
+  fi
+  answer=$(node "$bundle" "$repo" "$configured" 2>&1) || {
+    printf 'plot: cannot resolve the desk root: %s\n' "$answer" >&2
+    return 3
+  }
+  [ -n "$answer" ] || {
+    printf 'plot: the desk root rule answered nothing for %s\n' "$repo" >&2
+    return 3
+  }
+  printf '%s\n' "$answer"
+}
+
+# Keep the desk root out of `git status`, when it lies inside the repository.
+#
+# The line goes into the COMMON git directory's `info/exclude`: git reads that
+# file from the common directory only, so a linked worktree's private gitdir is
+# the wrong place and a desk writing there would exclude nothing. The write is
+# idempotent, and `info/exclude` is never committed.
+#
+# Called by whoever CREATES the directory. Best-effort and always exit 0: a
+# failure leaves untracked files in a listing, which is untidy, while refusing
+# to create a desk over it would stop the work.
+plot_exclude_desk_root() {
+  local repo="${1:-}" bundle="$_plot_desk_root_mjs" line common exclude configured
+  [ -n "$repo" ] || repo=$(plot_repo_root)
+  [ -f "$bundle" ] || return 0
+  configured=$(cd -- "$repo" 2>/dev/null && bash "$_plot_desk_root_config" get "Worktree root" "" 2>/dev/null) || configured=''
+  line=$(node "$bundle" --exclude-line "$repo" "$configured" 2>/dev/null) || return 0
+  # Empty means the root lies outside the repository, which needs no line.
+  [ -n "$line" ] || return 0
+  # Already ignored, by a `.gitignore` line /plot-init wrote or by an earlier
+  # run. A second rule for a path already ignored is noise in a file people read.
+  ( cd -- "$repo" 2>/dev/null && git check-ignore -q ".$line" ) && return 0
+  common=$(cd -- "$repo" 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null) || return 0
+  [ -n "$common" ] || return 0
+  case "$common" in /*) ;; *) common="$repo/$common" ;; esac
+  exclude="$common/info/exclude"
+  if [ -f "$exclude" ] && grep -qxF "$line" "$exclude" 2>/dev/null; then return 0; fi
+  mkdir -p "$common/info" 2>/dev/null || return 0
+  # A file not ending in a newline would otherwise join this line to its last.
+  if [ -s "$exclude" ] && [ "$(tail -c 1 "$exclude" 2>/dev/null)" != "" ]; then
+    printf '\n%s\n' "$line" >> "$exclude" 2>/dev/null || true
+  else
+    printf '%s\n' "$line" >> "$exclude" 2>/dev/null || true
+  fi
+  return 0
+}

package/plot-dispatch.sh

@@ -14,6 +14,8 @@
 #               hand each a queued slice with nobody touching a desk. The count
 #               is a REQUEST: a machine at its bound answers with fewer and says
 #               so, and the shortfall is reported rather than remembered.
+#               A `Worker command` that does not run plot-worker-loop.sh
+#               refuses (exit 1, `worker=no-loop`): only the loop waits.
 #   --restart <br>
 #               start a worker on <br>, which already holds a claim — the
 #               counterpart to --stop, and the only way to hand a stopped
@@ -217,40 +219,37 @@ 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  → repo_root/.. , prefix `plot-wt-`   (today's behaviour)
-#   relative value           → repo_root/<value> , NO prefix
-#   absolute value           → <value> as given , NO prefix
+#   `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.
+#
+# 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=""
 }
 
@@ -342,7 +341,7 @@ while [ $# -gt 0 ]; do
     # `--release` pushed it from 78 to 91. Two records
     # of one fact, and nothing compares them — a stale number here silently
     # truncates the help rather than failing, so it is checked by a test.
-    -h|--help)  sed -n '2,91p' "$0"; exit 0 ;;
+    -h|--help)  sed -n '2,93p' "$0"; exit 0 ;;
     *)          slug="$1" ;;
   esac
   shift
@@ -1022,6 +1021,46 @@ handover_refusal() { # $1=branch $2=worktree $3=state → 0 may hand over, 1 ref
   return 0
 }
 
+# WHICH COMMAND STARTS THIS AGENT is the domain's answer: `startCommand`, asked
+# through `board/plot-start-command.mjs`. An absent `Worker command` is not set
+# up and starts nothing, `none` is declined, and a free agent refuses a command
+# that does not run the loop (#1124). The loop's name and the value that runs it
+# are this script's readings; the rule names no script.
+#
+# THE VALUE IS THE BARE NAME, `PLOT_UNATTENDED=1 plot-worker-loop.sh`, the one
+# `/plot-init` writes: a plugin path carries a version and an absolute path
+# carries a machine. The launch puts this script's directory first on PATH, so
+# the bare name resolves to the loop shipped beside it.
+#
+# It sets `start_cmd_verb` (`run`, `unconfigured`, `declined`, `refused` or
+# `unaskable`), `start_cmd_run`, and `start_cmd_why` / `start_cmd_repair` where
+# they apply. `unaskable` is a bundle that could not answer, which starts
+# nothing.
+ask_start_command() { # $1 = free | assigned
+  local answer rc
+  start_cmd_verb="" start_cmd_run="" start_cmd_why="" start_cmd_repair=""
+  start_cmd_configured=$("$script_dir/plot-config.sh" get "Worker command" "")
+  start_cmd_bundle="$script_dir/board/plot-start-command.mjs"
+  answer=$(printf '%s' "$start_cmd_configured" | node "$start_cmd_bundle" "$1" \
+    plot-worker-loop.sh "PLOT_UNATTENDED=1 plot-worker-loop.sh" 2>/dev/null)
+  rc=$?
+  case "$rc:$answer" in
+    0:run$'\t'*) start_cmd_verb=run; start_cmd_run=${answer#run$'\t'} ;;
+    0:unconfigured$'\t'*)
+      start_cmd_verb=unconfigured
+      start_cmd_why="no 'Worker command' is configured"
+      start_cmd_repair=${answer#unconfigured$'\t'}
+      ;;
+    0:declined) start_cmd_verb=declined ;;
+    3:*)
+      start_cmd_verb=refused
+      start_cmd_why=${answer%%$'\n'*}
+      start_cmd_repair=${answer#*$'\n'}
+      ;;
+    *) start_cmd_verb=unaskable; start_cmd_why="the rule's bundle $start_cmd_bundle answered exit $rc" ;;
+  esac
+}
+
 start_worker() {
   local branch="$1" wt="$2"
   local cmd
@@ -1084,11 +1123,26 @@ start_worker() {
     return 1
   fi
 
-  cmd=$("$script_dir/plot-config.sh" get "Worker command" "")
   # `none` means "asked, and this repo starts them by hand". Running it would
   # spawn a worker per branch that fails with `none: command not found` — a
-  # deliberate answer turned into N crashed workers.
-  case "$cmd" in none|NONE|None) cmd="" ;; esac
+  # deliberate answer turned into N crashed workers. An absent key starts
+  # nothing either, and its line names the value to set.
+  ask_start_command "$([ -n "$branch" ] && echo assigned || echo free)"
+  case "$start_cmd_verb" in
+    run) cmd="$start_cmd_run" ;;
+    declined) cmd="" ;;
+    unconfigured)
+      echo "    worktree ready — ${start_cmd_why}, so nothing started:"
+      echo "      $start_cmd_repair."
+      echo "      cd $wt   # ${branch:+branch $branch is claimed and waiting}"
+      return 1
+      ;;
+    *)
+      echo "  refusing to start ${branch:-a free agent} — ${start_cmd_why}" >&2
+      [ -n "$start_cmd_repair" ] && echo "    Repair: $start_cmd_repair." >&2
+      return 1
+      ;;
+  esac
   if [ -z "$cmd" ]; then
     # Not an error: Plot deliberately hardcodes no agent tooling (Principle 5).
     # Word it as the next step rather than a failure, or a first run reads as
@@ -1099,11 +1153,7 @@ start_worker() {
     # in the summary, because per-branch output is exactly where it was missed
     # five times on 2026-08-17. Saying it in both places would train the reader
     # to skip both.
-    if [ "$worker_cmd_declined" = 1 ]; then
-      echo "    worktree ready — start it yourself:"
-    else
-      echo "    worktree ready — no 'Worker command' configured, so start it yourself:"
-    fi
+    echo "    worktree ready — start it yourself:"
     echo "      cd $wt   # branch $branch is claimed and waiting"
     return 1
   fi
@@ -1448,7 +1498,8 @@ start_worker() {
       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" \
-      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" '"'"'
+      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" '"'"'
         BEGIN { relaunch = 0; count = 1; stamped = 0 }
         FNR == NR {
           if ($0 ~ /^  "pid": "[^"]*",$/) {
@@ -1591,9 +1642,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)"
@@ -1725,11 +1780,30 @@ if [ "$mode" = "stop" ]; then
   case "$st" in
     running*)
       pid=${st#running }
-      kill "$pid" 2>/dev/null && echo "stopped $stop_branch (pid $pid)" \
+      # 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.
+      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"
+      case "$stop_pgid" in
+        ''|*[!0-9]*|0|1) ;;
+        *) [ "$stop_pgid" != "$stop_own_pgid" ] && stop_target="-$stop_pgid" ;;
+      esac
+      kill -TERM -- "$stop_target" 2>/dev/null && echo "stopped $stop_branch (pid $pid)" \
         || { echo "plot-dispatch: could not stop pid $pid — it may have exited between the read and the signal, or belong to another user." >&2
              echo "  Check it: ps -p $pid -o pid=,stat=,command=" >&2
              echo "  Nothing else was written; the worktree and the claim stand." >&2
              exit 1; }
+      if [ "$stop_target" = "$pid" ]; then
+        echo "  signalled pid $pid alone — its process group is unreadable or is this run's own"
+      else
+        echo "  signalled its whole process group $stop_pgid"
+      fi
       # The worktree and its claim are left in place: the branch is still taken,
       # and deleting either would be the kind of write this design avoids.
       echo "  worktree kept at $wt — the claim stands until you release it:"
@@ -2087,7 +2161,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
@@ -2233,6 +2306,38 @@ EOF
   start_headroom=${start_rest%%$'\t'*}
   start_why=${start_rest#*$'\t'}
 
+  # A FREE AGENT NEEDS THE LOOP, so a configured command that does not run it
+  # refuses here, before any desk is cut. A free agent starts with an empty
+  # `PLOT_BRANCH`, and only `plot-worker-loop.sh` waits for the registry to hand
+  # it a slice; any other command runs its prompt at once and exits. Measured
+  # 2026-10-01 (#1124): a plain `claude -p "… $PLOT_BRANCH …"` received
+  # "Implementiere den Branch in  nach dem Plan", exited within 30 s, and
+  # `--start` reported `agents=1`. A branch dispatch is not affected: a worker
+  # given a branch works on any command.
+  #
+  # THE DECISION IS THE DOMAIN'S: `ask_start_command` asks `startCommand`
+  # through its bundle. A refusal names the defect and the repair; a bundle that
+  # cannot answer starts nothing, as the fleet-size ask above does.
+  # `worker=no-loop` is the footer word the performer reads, the way it reads
+  # `unconfigured` and `declined`.
+  ask_start_command free
+  case "$start_cmd_verb" in
+    run|declined|unconfigured) ;;
+    refused)
+      echo "plot-dispatch: --start refuses — ${start_cmd_why}." >&2
+      echo "  configured: $start_cmd_configured" >&2
+      echo "  Repair: ${start_cmd_repair}." >&2
+      echo "  A branch dispatch (--restart <branch>) starts a worker on any command." >&2
+      echo "summary: agents=0 requested=${start_count:-default} running=$start_running headroom=$start_headroom worker=no-loop"
+      exit 1
+      ;;
+    *)
+      echo "plot-dispatch: --start could not ask which command starts an agent — starting none." >&2
+      echo "  ${start_cmd_why}." >&2
+      exit 1
+      ;;
+  esac
+
   echo "starting $start_n agent(s) — machine $start_headroom, $start_running already running"
 
   # THE WORKER COMMAND IS ASKED ONCE, BEFORE THE LOOP. `start_worker` prints its
@@ -2246,14 +2351,18 @@ EOF
   # summary — which is now a performer as well as a person — must be able to
   # tell *the machine bounded it* from *nobody has configured how to start one*.
   worker_cmd_declined=0
-  start_worker_state=configured
-  case "$("$script_dir/plot-config.sh" get "Worker command" "")" in
-    none|NONE|None) worker_cmd_declined=1; start_worker_state=declined ;;
-    '') start_worker_state=unconfigured ;;
+  case "$start_cmd_verb" in
+    declined) worker_cmd_declined=1; start_worker_state=declined ;;
+    unconfigured) start_worker_state=unconfigured ;;
+    *) start_worker_state=configured ;;
   esac
   if [ "$start_worker_state" != configured ]; then
     echo "  no worker will start — 'Worker command' is $start_worker_state in this repo's Plot Config."
-    echo "  The desks below are cut and registered; start them by hand, or set the key."
+    if [ "$start_worker_state" = unconfigured ]; then
+      echo "  The desks below are cut and registered. Repair: $start_cmd_repair."
+    else
+      echo "  The desks below are cut and registered; start them by hand, or set the key."
+    fi
   fi
 
   # `slug` STAYS EMPTY, and the loop reads it. A free agent belongs to no plan
@@ -2261,6 +2370,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
@@ -2314,6 +2426,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
@@ -2329,10 +2444,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)"
@@ -2375,8 +2487,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
 
@@ -2933,13 +3046,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
@@ -3180,6 +3292,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