@plot-pm/board 0.15.0 → 0.16.1

package/plot-config.sh

@@ -39,7 +39,11 @@
 #                       Non-numeric or empty falls back to the default. It bounds
 #                       a HUNG agent — one whose CLI crashed without exiting — so
 #                       one dead worker cannot hold a slot for hours.
-#   Agent registry      the directory the dispatcher writes agent manifests to,
+#   Temp sweep after    hours before `plot-reap.sh --sweep-temp` removes an
+#                       owned `$TMPDIR/plot-*` entry or a dead pid's budget
+#                       memo that a SIGKILL left behind. Default 24; a value
+#                       that is not a whole number is refused by the sweep.
+#   Agent registry     the directory the dispatcher writes agent manifests to,
 #                       read by the board's registry. Default `.plot/agents`
 #                       (repo-relative, gitignored, hence per-worktree). A board
 #                       served from a worktree the dispatcher never wrote to
@@ -48,6 +52,53 @@
 #                       the board finds the registry wherever it was started.
 #                       Absent = the default, so a single-checkout project is
 #                       unaffected.
+#   Board artifact      the board-server.mjs this repository runs, read by
+#                       plot-board-probe.sh. Declared, it is resolved FIRST and
+#                       reported as `artifact_source: checkout`; absent, the
+#                       order stays plugin, npm, checkout — the adopting
+#                       project's case, unchanged. It exists because a
+#                       repository that BUILDS the artifact must run the one it
+#                       built: without it `pnpm build:board` writes a file the
+#                       board never reads whenever a plugin is installed, and
+#                       the symptom looks like the fix not working.
+#                       A relative value resolves against the MAIN CHECKOUT (the
+#                       parent of `--git-common-dir`), never `--show-toplevel`,
+#                       so a dispatch desk resolves the same file rather than
+#                       its own copy; an absolute one is taken as given.
+#                       A declared file that is missing reports `none` and does
+#                       NOT fall back to the plugin — the key names which
+#                       artifact runs, so a silent substitution is the wrong
+#                       answer it removes. Absent = today's order.
+#   Agent settings      a JSON settings file every `claude -p` the fleet starts
+#                       is given, through `--settings`. It names the plugins this
+#                       project's agents start WITHOUT. Every dispatched agent
+#                       inherits every `SessionStart` hook the operator's plugins
+#                       declare, and the fleet starts a session on every worker
+#                       start, restart, retry and hop plus every agent-runner
+#                       command the board runs: measured 2026-09-30, one plugin's
+#                       lockless sync ran three times at once, the 1-minute load
+#                       reached 195, and the supervisor did not tick for 12
+#                       minutes.
+#                       Resolved by `plot-agent-settings.sh`, which prints an
+#                       absolute path (exit 0), nothing for an absent or empty key
+#                       (exit 0), or nothing with the reason on stderr (exit 3)
+#                       for a missing, unparseable or gate-disabling file. A
+#                       relative value resolves against the MAIN CHECKOUT (the
+#                       parent of `--git-common-dir`), never `--show-toplevel`,
+#                       for `Board artifact`'s reason: a desk must resolve the
+#                       same file, and one cut from an older main may not hold it.
+#                       The path travels to every consumer as
+#                       `PLOT_AGENT_SETTINGS`, and each command key interpolates
+#                       `${PLOT_AGENT_SETTINGS:+--settings "$PLOT_AGENT_SETTINGS"}`
+#                       itself — Plot rewrites no configured command.
+#                       A file setting any `plot@…` plugin false, `disableAllHooks`
+#                       true, or ANY `env` key is REFUSED: those switch Plot's own
+#                       four gates off, and a settings `PATH` hiding the gates'
+#                       tools makes them fail open. It is a check against an
+#                       accidental switch-off, not a boundary — the file is
+#                       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
@@ -58,14 +109,15 @@
 #                       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

@@ -51,6 +51,7 @@
 set -uo pipefail
 
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+. "$script_dir/plot-tmp.sh"
 
 # The receipt this script leaves for plot-state-gate.sh, which refuses every
 # other writer of a `State:` line. Sourced rather than run: the gate and the
@@ -660,7 +661,8 @@ git -C "$tmpwt" add -- "${DELIVERED_DIR#/}" >/dev/null 2>&1 || true
 # THE BOOKED PLAN, KEPT FOR THE TRACKER. The booking worktree is removed on
 # every exit below, and the working tree may still read `Approved`; the issue
 # status is decided from the file that reached the default branch.
-booked_plan=$(mktemp "${TMPDIR:-/tmp}/plot-deliver-plan.XXXXXX")
+booked_plan=""
+plot_tmpfile booked_plan deliver-plan
 cp "$tmpwt/$rel" "$booked_plan" 2>/dev/null || : > "$booked_plan"
 
 if git -C "$tmpwt" diff --cached --quiet 2>/dev/null; then

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
@@ -178,6 +180,7 @@
 set -uo pipefail
 
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+. "$script_dir/plot-tmp.sh"
 
 # The shared worker classifier. Sourced by both this script and
 # plot-fleet-scan.sh so a worker has ONE state, not one per reader.
@@ -341,7 +344,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
@@ -392,28 +395,9 @@ fi
 # until this moved. Nothing here executes at definition time; only the position
 # changed.
 
-# A session id, in the shape the runtime uses for its transcript filename.
-#
-# `uuidgen` where it exists (macOS and most Linux), falling back to `/dev/urandom`
-# — never to `$RANDOM` or a timestamp. Two workers launched in the same second by
-# the same fan-out would collide on either, and a collision here silently merges
-# two agents into one manifest.
-#
-# Lowercased because the runtime writes its transcript filename in lowercase and
-# the board joins on exact string equality; `uuidgen` on macOS returns uppercase.
-plot_session_id() {
-  local id=""
-  if command -v uuidgen >/dev/null 2>&1; then
-    id=$(uuidgen 2>/dev/null | tr 'A-Z' 'a-z')
-  fi
-  if [ -z "$id" ]; then
-    # 16 random bytes rendered as a v4-shaped id. The shape matters only for
-    # recognisability; nothing parses it.
-    id=$(od -An -tx1 -N16 /dev/urandom 2>/dev/null | tr -d ' \n' \
-         | sed -E 's/(.{8})(.{4})(.{4})(.{4})(.{12})/\1-\2-\3-\4-\5/')
-  fi
-  printf '%s' "$id"
-}
+# `plot_session_id` — the session id a launch records — is SOURCED from
+# `plot-agent-manifest.sh` above, because the worker loop mints one on a hop to
+# a new branch and two generators of one id drift.
 
 # JSON-escape one string for a manifest value.
 #
@@ -806,8 +790,20 @@ request_brief() { # $1 = branch, $2 = slug → 0 if a command was started
   # 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.
+  # 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
+  # worker loop exports — and the configured command interpolates
+  # `${PLOT_AGENT_SETTINGS:+--settings "$PLOT_AGENT_SETTINGS"}` itself.
+  #
+  # SET INLINE rather than exported, because this spawn already names its
+  # environment on the command line. A refusal or an absent key leaves it EMPTY,
+  # 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" \
     && PLOT_UNATTENDED=1 PLOT_PLAN_SLUG="$bslug" PLOT_BRIEF_BRANCH="$branch" \
+       PLOT_AGENT_SETTINGS="$_brief_settings" \
        nohup sh -c "$cmd \"\$@\"" plot-brief \
        "$(brief_prompt "$branch" "$bslug")" \
        >"$log" 2>&1 </dev/null & ) 2>/dev/null
@@ -1028,6 +1024,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
@@ -1090,11 +1126,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
@@ -1105,11 +1156,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
@@ -1454,7 +1501,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": "[^"]*",$/) {
@@ -1731,11 +1779,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:"
@@ -2239,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
@@ -2252,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
@@ -2659,18 +2762,18 @@ fi
 # materialised into a temp file rather than parsed here — the parser stays the
 # one place that knows what a plan file looks like.
 #
-# The template's X's must TRAIL: BSD mktemp (macOS) rejects a template with a
-# suffix after them, while GNU accepts it. The first version wrote
-# `plot-gate-XXXXXX.md` and failed on macOS — and because the failure fell back
-# to the working tree, the gate silently went back to reading the exact surface
-# this fix exists to stop reading. Hence also: NO working-tree fallback below.
-# If the shared blob cannot be materialised, the gate refuses.
+# `plot-tmp.sh` puts the template's X's last: BSD mktemp (macOS) rejects a
+# template with a suffix after them, while GNU accepts it. The first version
+# wrote `plot-gate-XXXXXX.md` and failed on macOS — and because the failure fell
+# back to the working tree, the gate silently went back to reading the exact
+# surface this fix exists to stop reading. Hence also: NO working-tree fallback
+# below. If the shared blob cannot be materialised, the gate refuses.
 plan_file="$plan_path"
 gate_blob=""
 if [ -n "$gate_sha" ]; then
-  gate_dir=$(mktemp -d "${TMPDIR:-/tmp}/plot-gate-XXXXXX") || gate_dir=""
+  gate_dir=""
+  plot_tmpdir gate_dir gate || gate_dir=""
   if [ -n "$gate_dir" ]; then
-    trap 'rm -rf "$gate_dir"' EXIT
     gate_blob="$gate_dir/$(basename "$plan_path")"
     git show "$gate_ref:$plan_path" >"$gate_blob" 2>/dev/null || gate_blob=""
   fi