@plot-pm/board 0.16.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Local Kanban board for Plot — a glanceable view of plan phases from docs/plans, with sprint and story filters",
   "type": "module",
   "license": "MIT",

package/plot-config.sh

@@ -109,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-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
@@ -342,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
@@ -1022,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
@@ -1084,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
@@ -1099,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
@@ -1448,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": "[^"]*",$/) {
@@ -1725,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:"
@@ -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

package/plot-fleet-scan.sh

@@ -2844,6 +2844,7 @@ is_plan_phase() { # $1=normalized phase → 0 when this file is a plan
 # gave when it failed.
 plan_meta_files=()
 plan_meta_phases=()
+plan_meta_types=()
 plan_meta_waves=()
 
 # Parses every plan file given, filling the four arrays above. Called ONCE.
@@ -2871,7 +2872,7 @@ for line in sys.stdin:
     f = d.get("file")
     if not f:
         continue
-    print("\t".join(["P", clean(f), clean(d.get("phase", ""))]))
+    print("\t".join(["P", clean(f), clean(d.get("phase", "")), clean(d.get("type", ""))]))
     for i, w in enumerate(d.get("waves", []) or []):
         name = w.get("name")
         for b in w.get("branches", []) or []:
@@ -2906,8 +2907,12 @@ for line in sys.stdin:
     case "$kind" in
       P)
         plan_meta_files+=("$file")
-        # `rest` is "<phase>", a single token with no tabs.
-        plan_meta_phases+=("$rest")
+        # `rest` is "<phase>\t<type>", two tokens with no tabs inside either.
+        plan_meta_phases+=("${rest%%$'\t'*}")
+        case "$rest" in
+          *$'\t'*) plan_meta_types+=("${rest#*$'\t'}") ;;
+          *) plan_meta_types+=("") ;;
+        esac
         plan_meta_waves+=("")
         ;;
       W)
@@ -3659,6 +3664,11 @@ for plan in "${plans[@]}"; do
   if is_terminal_phase "$plan_phase" && [ "$plan_phase" != "delivered" ]; then
     continue
   fi
+  # A docs or infra plan is live when it merges: /plot-release never records
+  # `Released` for one, so `delivered` is its last phase and it leaves here.
+  if [ "$plan_phase" = "delivered" ]; then
+    case "${plan_meta_types[$meta_i]}" in docs|infra) continue ;; esac
+  fi
 
   n_plans=$((n_plans + 1))
   plan_target=$(readlink "$plan" 2>/dev/null && echo "" || true)