@plot-pm/board 0.11.0 → 0.13.0

package/plot-dispatch.sh

@@ -2,10 +2,17 @@
 # Plot helper: hand one slice + its brief to the registry per eligible branch.
 # Usage: plot-dispatch.sh [--dry-run] [--no-start] [--no-brief] [--offline]
 #                         [--max N] [--allow-local] <slug>
+#        plot-dispatch.sh --start [N] [--dry-run]
 #        plot-dispatch.sh --migrate [--yes] [--max N]
 #   --status    list fleet worktrees with worker pid, liveness, and last log
 #               line; then exit. Works regardless of plan phase.
 #   --stop <br> stop the worker on <br> (branch required — never "all").
+#   --start [N] start N free agents — registered, waiting, holding no slice.
+#               Defaults to three. Each gets a desk detached at origin/<main>
+#               and a manifest naming no branch, so the registry's next tick can
+#               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.
 #   --restart <br>
 #               start a worker on <br>, which already holds a claim — the
 #               counterpart to --stop, and the only way to hand a stopped
@@ -151,6 +158,14 @@ script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck source=plot-pr-merged.sh
 . "$script_dir/plot-pr-merged.sh"
 
+# The ONE answer to "what is the default branch?" — `default_branch`, which
+# repairs an unresolvable `origin/HEAD` before it answers. This script is where
+# that corruption was MEASURED: twice on 2026-09-04 the symref pointed at
+# `origin/plot-corpus-pin`, and the refusal below fired on every dispatch. The
+# refusal stays; it now has less to refuse over.
+# shellcheck source=plot-default-branch.sh
+. "$script_dir/plot-default-branch.sh"
+
 # ---------------------------------------------------------------------------
 # WHERE THE WORKTREES LIVE, and by what name
 # ---------------------------------------------------------------------------
@@ -199,6 +214,10 @@ no_brief=0
 mode=dispatch
 stop_branch=""
 restart_branch=""
+# EMPTY MEANS "THE DEFAULT", AND THE DEFAULT IS THE RULE'S. `fleetSize` owns the
+# number and the argument for it; a literal here would be a second copy of a
+# decision that has one home. It is filled from the rule below.
+start_count=""
 offline=""
 allow_local=0
 allow_waiting=0
@@ -230,6 +249,16 @@ while [ $# -gt 0 ]; do
     # plan for feature/x", which describes neither what was asked nor what
     # went wrong. The branch is consumed only when it looks like one.
     --restart)  mode=restart; case "${2:-}" in */*) restart_branch="$2"; shift ;; esac ;;
+    # `--start [N]` brings FREE agents into existence — registered, waiting, and
+    # holding no slice. The count is OPTIONAL and only a bare number is consumed,
+    # the same rule `--stop` and `--restart` apply to a branch: a value that does
+    # not look like a count is left for the parser rather than swallowed, so
+    # `--start --dry-run` means what it reads as.
+    --start)    mode=start
+                case "${2:-}" in
+                  ''|*[!0-9]*) ;;
+                  *) start_count="$2"; shift ;;
+                esac ;;
     --no-start) no_start=1 ;;
     --no-brief) no_brief=1 ;;
     --offline|--no-fetch) offline="--offline" ;;
@@ -240,14 +269,18 @@ while [ $# -gt 0 ]; do
                   ''|*[!0-9]*) echo "plot-dispatch: --max needs a number, got '$max'" >&2; exit 1 ;;
                 esac
                 shift ;;
-    -h|--help)  sed -n '2,46p' "$0"; exit 0 ;;
+    -h|--help)  sed -n '2,59p' "$0"; exit 0 ;;
     *)          slug="$1" ;;
   esac
   shift
 done
 
 git rev-parse --git-dir >/dev/null 2>&1 || { echo "not a git repository" >&2; exit 1; }
-[ -n "$slug" ] || [ "$mode" != dispatch ] || { echo "plot-dispatch: need a plan slug" >&2; exit 1; }
+[ -n "$slug" ] || [ "$mode" != dispatch ] || {
+  echo "plot-dispatch: need a plan slug (usage: plot-dispatch.sh [--dry-run] <slug>)" >&2
+  echo "  Which plans could be dispatched: /plot-pulse" >&2
+  exit 1
+}
 
 # ---------------------------------------------------------------------------
 # Worker launch, and the identity it records
@@ -455,13 +488,202 @@ brief_prompt() { # $1 = branch, $2 = slug
     "$2" "$1" "$(brief_path "$1")" "$MAIN" "$MAIN"
 }
 
+# WHETHER THE AGENT THIS COMMAND SPAWNS CAN REACH `plot-implement` AT ALL.
+#
+# `Brief command` runs an agent headless and asks it for `/plot-implement
+# <slug>`. `plot-implement` is a SKILL, and a skill the running agent does not
+# have resolves to nothing. Measured 2026-09-06: Plot is installed as a plugin
+# at 1.2.0 against this repository's 2.13.0, and the installed `skills/` holds
+# eight — `plot-implement` is not among them, nor are `plot-dispatch`,
+# `plot-fleet`, `plot-pulse`, `plot-reconcile`, `plot-board`, `plot-init`,
+# `plot-merge-queue` or `plot-reslice`. Twelve are missing.
+#
+# So `Unknown command: /plot-implement` was LITERALLY TRUE in both 33-byte logs
+# (2026-09-02, 2026-09-04), and the board's *"Run /plot-implement `<slug>` and
+# follow it."* would have failed identically. The prompt's wording was never the
+# defect, and rewriting it fixes nothing.
+#
+# THE INSTALL BEING SCOPED TO ANOTHER PROJECT IS WHY FOUR MONTHS PASSED
+# UNNOTICED. The registry entry carries `scope: project` and `projectPath:
+# /Users/jwloka/Quatico/CDS/cpq-cds-develop` — a DIFFERENT repository, installed
+# 2026-05-08. A plugin installed elsewhere is not absent, it is somewhere else,
+# and nothing on this estate named that.
+#
+# IT ASKS WHETHER THE SKILL DIRECTORY EXISTS, NOT WHETHER THE VERSION MATCHES.
+# A lagging install that still carries the skill works, and a version comparison
+# would refuse it and demand an update nobody needs. One missing directory is
+# what breaks a brief session, so that is what is read.
+#
+# IT FAILS TOWARD ALLOWING. An unreadable or absent `installed_plugins.json`
+# means CANNOT VERIFY, not broken: a project running Plot from a checkout with
+# no plugin install at all is a supported shape, and refusing it would break
+# dispatch for everyone who never installed the plugin. It says the check could
+# not be made, and proceeds.
+#
+# `PLOT_PLUGIN_ROOT` is the override, the same one `plot-board-probe.sh` uses so
+# tests need not depend on `$HOME`.
+plugin_registry() { printf '%s/installed_plugins.json' "${PLOT_PLUGIN_ROOT:-${HOME:-}/.claude/plugins}"; }
+
+# Every `installPath` recorded for a plugin whose key starts `plot@`, one per
+# line. The marketplace half of the key is not fixed — `plot@plot-marketplace`
+# here, but a repository may serve Plot from a marketplace under any name — so
+# the prefix is what is matched rather than the whole key.
+#
+# `awk` rather than `node` or `jq`: this script shells to neither anywhere else,
+# and a check that fails toward allowing must not acquire a dependency whose
+# absence it would then have to read as "cannot verify" on every machine that
+# lacks it.
+#
+# IT DOES NOT DEPEND ON THE FILE'S LINE BREAKS. The registry Claude Code writes
+# is pretty-printed, one field per line, and a line-oriented read of it works —
+# but only because of how it happens to be formatted, and this check's wrong
+# answer is silent. Measured 2026-09-07 against a compact registry written by
+# hand: the whole object on two lines, and the reader found no install at all,
+# reported "could not verify" and allowed. Safe, and still wrong about a file
+# that was perfectly readable.
+#
+# So the text is flattened to one token per line FIRST — every `"…"` string and
+# every `[` `]` `{` `}` on its own line — and the scan then walks tokens rather
+# than lines. Formatting stops being an input.
+#
+# The bracket depth is what scopes a key: a plugin's entry runs from the `[`
+# after its key to the `]` that closes it, so an `installPath` is attributed to
+# the key whose array still encloses it. Tracking the key alone would let the
+# LAST `plot@…` key claim every install after it in the file.
+plugin_install_paths() { # → one installPath per line, for keys matching plot@*
+  awk '
+    {
+      line = $0
+      while (length(line) > 0) {
+        c = substr(line, 1, 1)
+        if (c == "\"") {
+          # A JSON string, taken whole: scan to the closing quote, honouring
+          # backslash escapes so a quote inside a value does not end it early.
+          v = ""; i = 2
+          while (i <= length(line)) {
+            ch = substr(line, i, 1)
+            if (ch == "\\") { v = v substr(line, i + 1, 1); i += 2; continue }
+            if (ch == "\"") break
+            v = v ch; i++
+          }
+          print "S" v
+          line = substr(line, i + 1)
+        } else if (c == "[" || c == "]" || c == "{" || c == "}") {
+          print "P" c
+          line = substr(line, 2)
+        } else {
+          line = substr(line, 2)
+        }
+      }
+    }
+  ' "$1" 2>/dev/null | awk '
+    # `pending` is the string most recently seen, which is a KEY when the next
+    # token opens a container. `depth` is where this plugin"s array closes.
+    /^P\[/ {
+      depth++
+      if (pending ~ /^plot@/ && inplot == 0) { inplot = 1; plotdepth = depth }
+      pending = ""; next
+    }
+    /^P\]/ {
+      if (inplot && depth == plotdepth) inplot = 0
+      depth--; pending = ""; next
+    }
+    /^P/ { pending = ""; next }
+    /^S/ {
+      v = substr($0, 2)
+      if (want) { if (inplot && v != "") print v; want = 0; pending = ""; next }
+      if (v == "installPath") { want = 1; next }
+      pending = v
+    }
+  '
+}
+
+# Can a spawned agent reach `plot-implement`?
+#
+#   0 — yes: some recorded install carries `skills/plot-implement/`
+#   1 — no: the registry was read, Plot is installed, and none of its installs
+#           carry the skill. This is the refusal.
+#   2 — cannot verify: no registry, unreadable, or no `plot@*` entry at all.
+#           Allowed, and said.
+#
+# The three-way answer is the whole point. Collapsing "cannot verify" into
+# either of the others is how this check would break a repository running Plot
+# from a checkout, or wave through the exact install that produced two empty
+# logs.
+implement_skill_reach() { # → 0 reachable, 1 unreachable, 2 unverifiable
+  local reg paths p
+  reg=$(plugin_registry)
+  [ -n "$reg" ] && [ -r "$reg" ] || return 2
+  paths=$(plugin_install_paths "$reg")
+  [ -n "$paths" ] || return 2
+  while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    case "$p" in "~/"*) p="${HOME:-}/${p#\~/}" ;; esac
+    [ -d "$p/skills/plot-implement" ] && return 0
+  done <<< "$paths"
+  return 1
+}
+
+# What the refusal SAYS, and it is the shape `plot-fleetctl.sh:306` uses for a
+# wrong `node` major — the reading first, then the repair.
+#
+# IT NAMES A REPAIR AN OPERATOR CAN PERFORM. Plot cannot install its own plugin;
+# updating an install is an action on a machine. So the message reports what was
+# read — which installs, and that none carries the skill — and names the command
+# that fixes it. Nothing here installs or updates anything.
+implement_unreachable_report() { # prints the reading and the repair, indented
+  local reg p
+  reg=$(plugin_registry)
+  echo "      no-implement-skill — the agent this would spawn cannot reach \`/plot-implement\`"
+  echo "      read: $reg"
+  while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    echo "        install: $p (no skills/plot-implement/)"
+  done <<< "$(plugin_install_paths "$reg")"
+  echo "      A prompt naming a skill the agent does not have resolves to nothing,"
+  echo "      whatever its wording — measured twice as a 33-byte log reading"
+  echo "      \`Unknown command: /plot-implement\`. Refusing before spawning is what"
+  echo "      puts that in front of you instead of in a log nobody reads."
+  echo "      Fix it: update the Plot plugin so its skills/ carries plot-implement"
+  echo "      (/plugin, or reinstall from the marketplace), then dispatch again."
+  echo "      Or write the brief yourself: /plot-implement $1"
+}
+
+# THE THIRD ANSWER, and it allows. A registry that cannot be read says nothing
+# about whether the skill is there — a project running Plot from a checkout with
+# no plugin install at all is a supported shape, and refusing it would break
+# dispatch for everyone who never installed the plugin. So the run says the
+# check could not be made and proceeds, which is what keeps a silent skip from
+# reading as a verified pass.
+implement_unverifiable_note() {
+  echo "      could not verify that the agent can reach the implement skill —"
+  echo "      no readable plugin registry at $(plugin_registry); proceeding"
+}
+
 request_brief() { # $1 = branch, $2 = slug → 0 if a command was started
-  local branch="$1" bslug="$2" cmd log
+  local branch="$1" bslug="$2" cmd log reach
   cmd=$(brief_command)
   if [ -z "$cmd" ]; then
     echo "      no-brief-command — no \`Brief command\` in Plot Config, so nothing was asked to write it"
     return 1
   fi
+  # REFUSES BEFORE SPAWNING, NEVER AFTER. Failing late cost two logs nobody
+  # read and a session writing nine briefs by hand without asking why the arm
+  # was silent. The refusal is read by whoever ran the dispatch.
+  #
+  # A DIFFERENT REFUSAL FROM `no-brief-command`, and it gets its own word rather
+  # than overloading that one: there the key is absent and nothing was asked to
+  # write the brief; here the key is SET and the skill it names is unreachable.
+  # One word for two states is a word an operator cannot act on.
+  implement_skill_reach
+  reach=$?
+  if [ "$reach" = 1 ]; then
+    implement_unreachable_report "$bslug"
+    return 1
+  fi
+  if [ "$reach" = 2 ]; then
+    implement_unverifiable_note
+  fi
   log="$repo_root/.plot/brief-$(printf '%s' "${branch##*/}").log"
   mkdir -p "$(dirname "$log")" 2>/dev/null || true
   # `nohup ... &` inside a subshell, the same detachment `start_worker` uses:
@@ -950,14 +1172,38 @@ if [ "$mode" = "stop" ]; then
     echo "  Refusing to guess — stopping the wrong worker discards its work." >&2
     exit 1
   fi
-  wt="$wt_root_early/$wt_prefix_early$(printf '%s' "$stop_branch" | tr '/' '-')"
-  [ -d "$wt" ] || { echo "plot-dispatch: no worktree for '$stop_branch' at $wt" >&2; exit 1; }
+  # ASK GIT WHICH WORKTREE HOLDS THE BRANCH, then fall back to the dispatch
+  # path. `--restart` below already asks, and this did not: it rebuilt one path
+  # from the branch name and reported that single path as though it were the
+  # only place a desk could be. On 2026-09-07 the desk existed elsewhere — a
+  # worktree made by hand, which is the population that never follows
+  # dispatch's naming — and the refusal sent a reader to `kill`.
+  #
+  # 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_guess="$wt_root_early/$wt_prefix_early$(printf '%s' "$stop_branch" | tr '/' '-')"
+  [ -n "$wt" ] && [ -d "$wt" ] || wt="$wt_guess"
+  if [ ! -d "$wt" ]; then
+    echo "plot-dispatch: no worktree holds '$stop_branch' — nothing to stop." >&2
+    echo "  Asked git for every worktree, and looked at $wt_guess." >&2
+    echo "  If a worker is running somewhere this cannot see, that machine is" >&2
+    echo "  where to stop it: /plot-dispatch --status names the desks here." >&2
+    echo "  Nothing was killed." >&2
+    exit 1
+  fi
   st=$(worker_state "$wt" "$stop_branch")
   case "$st" in
     running*)
       pid=${st#running }
       kill "$pid" 2>/dev/null && echo "stopped $stop_branch (pid $pid)" \
-        || { echo "plot-dispatch: could not stop pid $pid" >&2; exit 1; }
+        || { 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; }
       # 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"
@@ -1100,6 +1346,284 @@ if [ "$mode" = "restart" ]; then
   exit 0
 fi
 
+if [ "$mode" = "start" ]; then
+  # THE LAST LINK IN THE CHAIN. `plot-dispatch.sh <slug>` queues slices and the
+  # registry matches them to free agents, but until this verb existed nothing
+  # brought a free agent into being. Measured 2026-09-05: a dispatch reported
+  # `handed over feature/... → the registry` and `started=0`, the supervisor
+  # ticked `queued=456 idle=0 agents registered: 0`, and `.plot/agents/` was
+  # empty. The slice was queued, the registry was willing, and there was nobody
+  # to hand it to.
+  #
+  # AN AGENT IS STARTED WITH NO SLICE, and that is the whole shape. It gets a
+  # desk, a manifest naming no branch, and a loop that waits — `isAgentFree`
+  # already reports exactly that state as free (`rules/free.ts:64`: alive, and
+  # `branch === ""`), so the supervisor's next tick can hand each one a queued
+  # slice with nobody touching a desk.
+  #
+  # HERE, BESIDE --stop AND --restart AND BEFORE THE PHASE GATE, for the reason
+  # that block already gives from the other side: starting a free agent is not
+  # 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
+  # fan-out's `MAIN` is set past the phase gate this path exits before.
+  start_main=$(bash "$script_dir/plot-config.sh" get "Main branch")
+  [ -n "$start_main" ] || start_main=$(default_branch)
+  [ -n "$start_main" ] || start_main="main"
+
+  # HOW MANY WORKERS ARE ALREADY UP, counted from the desks on this disk rather
+  # than from the registry. A manifest records a launch; a live pid records a
+  # worker, and the question `--start` asks is about the machine's load. The
+  # count is what `fleetSize` subtracts, so asking for three twice gives three
+  # agents rather than six.
+  #
+  # A CALLER THAT HAS ALREADY DECIDED THE COUNT SUBTRACTS NOTHING, and
+  # `PLOT_START_ONE` is how it says so. The supervisor's tick ran `fleetSize`
+  # against the WHOLE fleet, decided N, and hands this script one write at a
+  # time; re-counting per call subtracts the agent the PREVIOUS call just
+  # started. Measured 2026-09-05 in a sandbox: a tick that decided `started=3`
+  # produced ONE agent, because calls two and three each saw a fleet already
+  # the size they were asked for.
+  #
+  # SO IT MEANS *START THIS ONE*: the count is one and the subtraction is
+  # skipped. The machine keeps its veto — a starved one still answers with
+  # fewer, which is the reading that must not be skipped, because it is about
+  # the load this very call would add.
+  #
+  # A SEPARATE VARIABLE FROM `PLOT_START_DESK`, and not a side effect of it.
+  # The two answer different questions — *where does this desk go* and *has the
+  # count already been decided* — and the caller that has decided the count is
+  # not always the caller that can name a path. The supervisor is exactly that
+  # caller: the domain names no worktree, so it sets this and leaves the path
+  # to the script's own `Worktree root` convention.
+  start_running=0
+  if [ -n "${PLOT_START_ONE:-}" ]; then
+    start_count=1
+  else
+  while IFS= read -r wt; do
+    [ -n "$wt" ] || continue
+    [ -f "$wt/.plot-worker.pid" ] || continue
+    p=$(cat "$wt/.plot-worker.pid" 2>/dev/null) || continue
+    [ -n "$p" ] && ps -p "$p" >/dev/null 2>&1 && start_running=$((start_running + 1))
+  done <<EOF
+$(git worktree list --porcelain </dev/null 2>/dev/null | awk '/^worktree /{print $2}')
+EOF
+  fi
+
+  # THE MACHINE'S OWN READING, one timed fork. `machine-system.ts` samples five
+  # and divides; this takes ONE, because the decision it feeds is coarse — three
+  # bands — and a start that spent 250 ms sampling before deciding whether the
+  # machine is busy would be the story's own complaint reproduced by its fix.
+  #
+  # UNMEASURABLE IS NOT STARVED. A `date` that cannot answer in milliseconds
+  # (BSD `date` without `%N`) leaves the cost empty, the rule reads `unmeasured`,
+  # and an absent veto is not a refusal. The machine vetoes what it can measure.
+  #
+  # THE CLOCK IS BASH'S OWN `EPOCHREALTIME`, not `date` and not `python3`. Both
+  # of those are a FORK, which is precisely the thing being timed — the
+  # measurement would cost two of what it measures and report the sum. Bash 5
+  # expands `EPOCHREALTIME` in-process; where it is empty (bash 4, still the
+  # system shell on macOS) the cost stays unmeasured, which the rule reads as
+  # `unmeasured` rather than as clear.
+  start_cost=""
+  if [ -n "${EPOCHREALTIME:-}" ]; then
+    start_t0=${EPOCHREALTIME/[.,]/}
+    git -C "$repo_root" rev-parse --git-dir >/dev/null 2>&1
+    start_t1=${EPOCHREALTIME/[.,]/}
+    # Microseconds to milliseconds. Integer division, so a fork faster than a
+    # millisecond reports 0 — which is honest about a machine this clear and is
+    # the same band `clear` covers anyway.
+    case "$start_t0$start_t1" in
+      *[!0-9]*) ;;
+      *) start_cost=$(( (start_t1 - start_t0) / 1000 )) ;;
+    esac
+  fi
+
+  # THE COUNT IS THE RULE'S, and the rule is `packages/domain/src/rules/
+  # fleet-size.ts` — imported directly, the same shape `plot-reap.sh` uses for
+  # `reapable.ts`. Node 24 strips the types, so there is no build step between
+  # this script and the decision it asks for, and there is no second copy of the
+  # default, the subtraction or the machine's veto living in shell.
+  #
+  # A RULE THAT CANNOT BE ASKED STARTS NOTHING AND SAYS SO. Missing node, a
+  # failed import, a module that throws all leave the answer empty. The
+  # direction is the reaper's: silence is never permission, and here permission
+  # would spawn detached processes.
+  #
+  # TWO MODULES, BECAUSE THE VERDICT AND THE COUNT ARE TWO RULES. `headroomFor`
+  # owns what a fork cost MEANS and `fleetSize` owns what to do about it; the
+  # count rule takes the verdict as a reading rather than deriving it, so the
+  # thresholds have exactly one home and this block is the join.
+  #
+  # IMPORTED AS `.ts` WITH NO `.js` REWRITING. Node 24 strips types but does not
+  # remap a relative specifier, so `fleet-size.ts` may only `import type` from
+  # its neighbours — which is why the verdict arrives as a value here rather
+  # than being computed inside the rule.
+  start_domain="$(cd "$script_dir/../../.." 2>/dev/null && pwd)/packages/domain/src"
+  start_rule="file://$start_domain/rules/fleet-size.ts"
+  start_answer=$(PLOT_REQUESTED="$start_count" PLOT_RUNNING="$start_running" \
+                 PLOT_COST="$start_cost" PLOT_RULE="$start_rule" \
+                 PLOT_MACHINE="file://$start_domain/entities/machine.ts" \
+                 node --input-type=module - <<'NODE_EOF' 2>/dev/null
+const { fleetSize, DEFAULT_FLEET_SIZE } = await import(process.env.PLOT_RULE);
+const { headroomFor } = await import(process.env.PLOT_MACHINE);
+
+// AN ABSENT COUNT IS THE RULE'S DEFAULT, resolved here rather than in the
+// shell: the number and the argument for it have one home.
+const requested =
+  process.env.PLOT_REQUESTED === "" ? DEFAULT_FLEET_SIZE : Number(process.env.PLOT_REQUESTED);
+
+// An UNMEASURED cost is null, never zero: zero is the fastest fork there is and
+// would read as the clearest possible machine.
+const spawnCostMs = process.env.PLOT_COST === "" ? null : Number(process.env.PLOT_COST);
+
+const answer = fleetSize({
+  requested,
+  running: Number(process.env.PLOT_RUNNING),
+  spawnCostMs,
+  headroom: headroomFor(spawnCostMs),
+});
+
+process.stdout.write(`${answer.start}\t${answer.headroom}\t${answer.shortfall}`);
+NODE_EOF
+  )
+
+  if [ -z "$start_answer" ]; then
+    echo "plot-dispatch: --start could not ask how many agents to start — starting none." >&2
+    echo "  The rule is $start_rule" >&2
+    echo "  It needs node 24 and a readable checkout of packages/domain." >&2
+    exit 1
+  fi
+
+  start_n=${start_answer%%$'\t'*}
+  start_rest=${start_answer#*$'\t'}
+  start_headroom=${start_rest%%$'\t'*}
+  start_why=${start_rest#*$'\t'}
+
+  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
+  # own "start it yourself" line per agent when the key is absent, and N
+  # identical copies of it is a wall rather than a message. Asked here, the
+  # refusal is one sentence naming what to configure.
+  #
+  # THE THREE-WAY ANSWER IS THE FAN-OUT'S OWN `worker=` FIELD, in the footer for
+  # the same reason it is there: `agents=0` with no reason beside it is what was
+  # printed and missed five times on 2026-08-17. A caller reading only the
+  # 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 ;;
+  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."
+  fi
+
+  # `slug` STAYS EMPTY, and the loop reads it. A free agent belongs to no plan
+  # — the registry sends the slug WITH the assignment, which is the same reason
+  # `wait_for_work` skips the outlook scan for an agent that holds none.
+  slug=""
+
+  start_made=0
+  start_i=0
+  while [ "$start_i" -lt "$start_n" ]; do
+    start_i=$((start_i + 1))
+
+    # THE DESK IS DETACHED AT `origin/<main>`, AND NEITHER HALF IS INCIDENTAL.
+    #
+    # A free agent still needs a desk: the loop reads `${PLOT_WORKTREE:-$PWD}`
+    # throughout and the transcript directory is derived from that path. It has
+    # no branch to cut one from, so the base is the only thing left — which is
+    # what the loop's own hop already does. `reset_desk` step 1 checks out
+    # `origin/$main_branch` DETACHED before attaching the slice's branch, so a
+    # desk that starts detached at the base is where every reset passes through
+    # anyway, and the first hand-over is a plain `checkout -b` from it.
+    #
+    # DETACHED RATHER THAN ON THE DEFAULT BRANCH, and that is the guard. A tree
+    # sitting on the default branch is one of `plot-reap.sh`'s five refusals
+    # (`on-default-branch`) — so it is never reaped, but it is also never
+    # measured: the refusal exists because that tree's dispatched branch was
+    # never checked out. A detached desk reads `branch: ''`, so the refusal that
+    # keeps it is `no-merged-pr` — unlanded work, the honest reading of a desk
+    # holding nothing yet — and it is kept for a reason that describes it.
+    #
+    # Git refuses to check out one branch in two worktrees, and the main
+    # checkout usually holds the default branch, so an attached desk could not
+    # be cut here at all.
+    # THE DESK PATH IS THE SCRIPT'S UNLESS A CALLER NAMED ONE.
+    #
+    # `PLOT_START_DESK` is how the supervisor's performer passes the desk the
+    # DECISION named. It is an environment variable rather than a flag because
+    # it takes exactly one path and is set by exactly one caller: a flag would
+    # put a machine-only interface in the help text an operator reads, beside
+    # the count they actually type. A person typing `--start 3` never names
+    # three paths.
+    #
+    # It applies to ONE desk, so a run that was handed it starts one agent —
+    # `fleetSize` is what decides the count and the performer applies its writes
+    # one at a time, which is what keeps the decision and the writes in step.
+    if [ -n "${PLOT_START_DESK:-}" ]; then
+      start_wt="$PLOT_START_DESK"
+    else
+      start_wt="$wt_root/${wt_prefix}free-$(plot_session_id | cut -c1-8)"
+    fi
+    if [ -e "$start_wt" ]; then
+      echo "  skipped $start_wt — a desk of that name already exists"
+      continue
+    fi
+    if [ "$dry_run" = 1 ]; then
+      echo "  would create $start_wt (detached at origin/$start_main) and start a free agent"
+      start_made=$((start_made + 1))
+      continue
+    fi
+    mkdir -p "$wt_root" 2>/dev/null || true
+    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
+      # in every case that matters, and a desk on it is still detached.
+      if ! git worktree add -q --detach "$start_wt" "$start_main" 2>/dev/null; then
+        echo "  could not create a desk at $start_wt — skipping" >&2
+        continue
+      fi
+    fi
+
+    # SPOTLIGHT IS TOLD NOT TO INDEX THE DESK, exactly as the loop's hop does.
+    # A desk is a full checkout and the fleet makes and unmakes them all day;
+    # 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
+    : > "$start_wt/.metadata_never_index" 2>/dev/null || true
+
+    echo "  desk $start_wt (detached at origin/$start_main)"
+    # THE EMPTY BRANCH IS THE WHOLE POINT, and `start_worker` already takes it
+    # as a parameter: `write_agent_manifest` writes `"branch": ""`, the loop
+    # reads `PLOT_BRANCH` empty and enters its wait rather than its prompt, and
+    # `isAgentFree` reports the agent free with no change to `rules/free.ts`.
+    if start_worker "" "$start_wt"; then
+      start_made=$((start_made + 1))
+    fi
+  done
+
+  # THE SHORTFALL IS SAID HERE AND STORED NOWHERE. An operator reads it and runs
+  # the command again; a remembered target would be the first piece of state in
+  # a fleet whose statelessness is measured rather than assumed.
+  [ -n "$start_why" ] && echo "  $start_why"
+  echo "summary: agents=$start_made requested=${start_count:-default} running=$start_running headroom=$start_headroom worker=$start_worker_state"
+  exit 0
+fi
+
 # ---------------------------------------------------------------------------
 # Migration mode: move legacy worktrees into the configured root
 # ---------------------------------------------------------------------------
@@ -1312,8 +1836,7 @@ fi
 # exactly where nothing can catch it. --allow-local is the explicit escape, and
 # it is named in the refusal so an operator learns it exists when they need it.
 MAIN=$(bash "$script_dir/plot-config.sh" get "Main branch")
-[ -n "$MAIN" ] || MAIN=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')
-[ -n "$MAIN" ] || MAIN="main"
+[ -n "$MAIN" ] || MAIN=$(default_branch)
 [ -n "$offline" ] || git fetch -q origin "$MAIN" 2>/dev/null
 
 PLAN_DIR_CFG=$("$script_dir/plot-config.sh" get "Plan directory" "docs/plans/")
@@ -1389,6 +1912,7 @@ fi
 if [ -z "$plan_path" ]; then
   if [ "$allow_local" = 1 ]; then
     echo "plot-dispatch: no plan found for '$slug' — looked in $ACTIVE_DIR_CFG and $PLAN_DIR_CFG" >&2
+    echo "  Check the slug: ls $PLAN_DIR_CFG | grep -i '$slug'" >&2
   else
     echo "plot-dispatch: no plan for '$slug' on $gate_ref — looked in $ACTIVE_DIR_CFG and $PLAN_DIR_CFG" >&2
     echo "  A plan that exists only in this working tree has not been shared yet: push it first." >&2
@@ -1449,6 +1973,7 @@ case "$gate_phase" in
     exit 1 ;;
   delivered|released)
     echo "plot-dispatch: plan '$slug' is already $gate_phase — its work is done." >&2
+    echo "  Nothing to dispatch. To start new work: /plot-idea" >&2
     exit 1 ;;
   "")
     echo "plot-dispatch: cannot read the phase of '$slug' ($gate_source)." >&2
@@ -1456,6 +1981,8 @@ case "$gate_phase" in
     exit 1 ;;
   *)
     echo "plot-dispatch: plan '$slug' is in phase '$gate_phase', not Approved." >&2
+    echo "  Correct the 'State:' line in the plan and push it, or approve it:" >&2
+    echo "  /plot-approve $slug" >&2
     exit 1 ;;
 esac
 
@@ -1467,6 +1994,7 @@ case "$gate_impl" in
   same-branch)
     echo "plot-dispatch: plan '$slug' records 'Impl: same branch' — plan and code" >&2
     echo "  travel on one branch, so there is nothing to fan out." >&2
+    echo "  Implement on that branch instead: /plot-implement $slug" >&2
     exit 1 ;;
   other-repo)
     echo "plot-dispatch: plan '$slug' records 'Impl: other repo' — implementation" >&2
@@ -1479,6 +2007,8 @@ case "$gate_impl" in
   *)
     echo "plot-dispatch: plan '$slug' records an unrecognised 'Impl:' answer" >&2
     echo "  ('$gate_impl'). Refusing rather than guessing." >&2
+    echo "  Set the plan's 'Impl:' line to one of: own branches, same branch," >&2
+    echo "  other repo, none — then push it." >&2
     exit 1 ;;
 esac
 
@@ -1908,7 +2438,8 @@ write_started_record() { # $@ = branches
   # would carry the symlink and leave the record behind.
   rel=$(cd "$repo_root" && real_plan_path "$plan_file") || rel=""
   if [ -z "$rel" ]; then
-    echo "plot-dispatch: $plan_file is outside the repository root" >&2
+    echo "plot-dispatch: $plan_file is outside the repository root ($repo_root)." >&2
+    echo "  Move the plan under $PLAN_DIR_CFG inside this checkout and re-run." >&2
     return 1
   fi
 
@@ -1924,6 +2455,9 @@ write_started_record() { # $@ = branches
   # one. It is disposable by construction — created here, pushed, deleted.
   if ! git worktree add -q -B "$bookbr" "$tmpwt" "origin/$MAIN" 2>/dev/null; then
     echo "plot-dispatch: could not prepare a booking worktree at $tmpwt" >&2
+    echo "  Most often origin/$MAIN is not fetched, or '$bookbr' is checked out in" >&2
+    echo "  another worktree. Check both: git fetch origin $MAIN && git worktree list" >&2
+    echo "  The branches were dispatched; only the plan's Started record is missing." >&2
     return 1
   fi
 
@@ -1947,6 +2481,7 @@ write_started_record() { # $@ = branches
       fi
       append_started_line "$tmpwt/$rel" "$date" "$who" "$br" || {
         echo "plot-dispatch: $rel has no '## Status' section — nowhere to record" >&2
+        echo "  Add one to the plan (see .plot/templates/plan.md) and push it." >&2
         rc=1
         break
       }
@@ -1968,6 +2503,7 @@ write_started_record() { # $@ = branches
     fi
   else
     echo "plot-dispatch: $rel is not on origin/$MAIN" >&2
+    echo "  Push the plan to $MAIN first; the fleet reads plans from the shared ref." >&2
     rc=1
   fi
 
@@ -2412,7 +2948,7 @@ report_in_flight() { # $1=candidate branch
       # Said once, on the last line, rather than per branch.
       [ "$n" = "$((IN_FLIGHT_MAX_BRANCHES + 1))" ] && \
         echo "  in flight: …and $((total - IN_FLIGHT_MAX_BRANCHES)) more branches" \
-             "— plot-fleet for the full picture"
+             "— plot-pulse for the full picture"
       continue
     fi
     # Commas to ", " for reading; the machine-countable summary is the footer,