@plot-pm/board 0.14.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plot-pm/board",
-  "version": "0.14.0",
+  "version": "0.14.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-dispatch.sh

@@ -281,12 +281,20 @@ while [ $# -gt 0 ]; do
   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 (usage: plot-dispatch.sh [--dry-run] <slug>)" >&2
-  echo "  Which plans could be dispatched: /plot-pulse" >&2
-  exit 1
-}
+# THE TWO PRECONDITIONS OF A DISPATCH, and a sourcing test has neither.
+# `PLOT_DISPATCH_SOURCED=1` is taking the definitions below rather than running
+# a dispatch, so it has no slug and often no git repository; the guard that
+# stops it sits further down, after the function it exists to expose, and these
+# two would exit before it is reached. See that guard for why it cannot simply
+# move up here.
+if [ -z "${PLOT_DISPATCH_SOURCED:-}" ]; then
+  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 (usage: plot-dispatch.sh [--dry-run] <slug>)" >&2
+    echo "  Which plans could be dispatched: /plot-pulse" >&2
+    exit 1
+  }
+fi
 
 # ---------------------------------------------------------------------------
 # Worker launch, and the identity it records
@@ -743,9 +751,207 @@ brief_staleness_note() { # $1 = branch → prints a hint, or nothing
   echo "      plan commit ${pc%% *} touched $plan_path after the brief's last change; read it before trusting the brief"
 }
 
+# ---------------------------------------------------------------------------
+# WHAT THIS AGENT RUNS
+# ---------------------------------------------------------------------------
+#
+# THE HARNESS IS RESOLVED, NOT ASSUMED. `Worker command` is one key and every
+# dispatched agent got the identical command line, so a fleet could not hold a
+# reviewer on one model beside an implementer on another. A charter
+# (`.plot/charters/<name>.json`) names its own `harness`, `model` and `effort`,
+# and `plot-prompt.mjs --launch` decides which apply.
+#
+# A CHARTER NAMES A HARNESS; IT NEVER CARRIES A COMMAND LINE. Plot exports the
+# three names and the PROMPT FILE holds the invocation — the contract
+# `.plot/worker-prompt.sh` already states: *"Plot exports the variables and
+# cannot write the invocation."* So this sets three variables and never builds
+# a command out of them.
+#
+# NOTHING ON THE ESTATE CHANGES UNTIL A CHARTER EXISTS. `$PLOT_AGENT` unset —
+# which is every worker today, since the estate holds zero charters — exports
+# none of the three, and the command line is byte-identical to what it was.
+# So does a named agent with no charter file on this clone.
+#
+# A REFUSAL IS NOT A FALLBACK, for `resolve_prompt_file`'s reason one field
+# over: a charter that cannot be believed would otherwise RUN, successfully,
+# under an invocation the operator did not ask for, and nothing in
+# `.plot-worker.log` would say so.
+#
+# A HARNESS THIS MACHINE CANNOT RUN IS THE SECOND REFUSAL, and it is a MACHINE
+# fact rather than a charter one. `plot-prompt.mjs` answers what a charter
+# DECLARES and reaches no machine; whether the name is on PATH is the adapter's
+# question, asked here, in the shell that is about to spawn — beside the `node`
+# and `launchd` probes `plot-fleetctl.sh` performs. Without it a typo in a hand
+# written field (`agnet` for `agent`) exports a name the prompt file then
+# ignores, and the work is done by the repo default with nothing saying so.
+#
+# THE BUNDLE MISSING IS ALSO NOT A REFUSAL. `plot-prompt.mjs` is vendored beside
+# this script, and a checkout without it is a Plot installation problem rather
+# than a statement about this agent — so it falls back and SAYS it could not
+# ask, the shape `plot-dispatch.sh:1502` already uses for an unaskable rule.
+#
+# It sets `launch_harness`, `launch_model`, `launch_effort` and `launch_agent`,
+# and returns 1 on a refusal; the caller decides what a refusal costs.
+resolve_launch() { # $1 = repo root, $2 = agent name ('' when none)
+  local root="$1" agent="$2" resolution="" status=0 verb rest why
+  launch_harness=""
+  launch_model=""
+  launch_effort=""
+  launch_agent=""
+
+  if [ -f "$script_dir/board/plot-prompt.mjs" ]; then
+    resolution=$(node "$script_dir/board/plot-prompt.mjs" --launch "$root" "$agent" 2>/dev/null)
+    status=$?
+  else
+    echo "plot-dispatch: no plot-prompt.mjs beside this script — starting ${agent:-this agent} on the repo's 'Worker command' without asking what it declared" >&2
+    return 0
+  fi
+
+  verb=${resolution%%$'\t'*}
+  rest=${resolution#*$'\t'}
+  launch_harness=${rest%%$'\t'*}
+  rest=${rest#*$'\t'}
+  launch_model=${rest%%$'\t'*}
+  rest=${rest#*$'\t'}
+  launch_effort=${rest%%$'\t'*}
+  why=${rest#*$'\t'}
+
+  if [ "$status" -eq 3 ] || [ "$verb" = "refused" ]; then
+    launch_harness=""
+    launch_model=""
+    launch_effort=""
+    launch_why="$why"
+    return 1
+  fi
+
+  case "$verb" in
+    declared)
+      launch_agent="$why"
+      # A HARNESS THIS MACHINE CANNOT RUN REFUSES. `command -v` is the reading
+      # because it is the question the prompt file asks when it interpolates the
+      # name: a check that asked anything else would refuse launches that work
+      # and pass launches that will not. It sits on this arm because only
+      # `declared` carries a harness the launch exports — the refusal above and
+      # the `*)` arm below have both already blanked the field.
+      #
+      # AN UNNAMED HARNESS IS NOT AN UNRUNNABLE ONE. A charter naming none
+      # resolves to '' and launches exactly as it does today, which is every
+      # dispatch on the estate; the guard on a non-empty name is what keeps it
+      # that way.
+      if [ -n "$launch_harness" ] && ! command -v "$launch_harness" >/dev/null 2>&1; then
+        # The name is read BEFORE the fields are blanked: the refusal's whole
+        # job is to name what it looked for, and clearing first loses it.
+        why="charter '$launch_agent' names harness '$launch_harness', which is not on PATH"
+        launch_harness=""
+        launch_model=""
+        launch_effort=""
+        launch_why="$why"
+        return 1
+      fi
+      ;;
+    *)
+      # A fallback, an unrecognised verb, or an empty answer from a bundle that
+      # could not run. Three empty names, which is what every worker exports
+      # today.
+      launch_harness=""
+      launch_model=""
+      launch_effort=""
+      ;;
+  esac
+  return 0
+}
+
+# WHETHER A DESK MAY BE HANDED TO A NEW WORKER — the ONE gate, two callers.
+#
+# EXTRACTED RATHER THAN COPIED, and that is the point. `--restart` asked these
+# three questions inline; `--absent` asks the same three over every orphaned
+# desk. A second, laxer set written for the sweep is the failure
+# `plot-dispatch --stop` already argues against for stop rules, and it matters
+# more here because the sweep runs with nobody watching.
+#
+# IT RETURNS RATHER THAN EXITS, which is the only change the extraction makes.
+# A verb acting on one branch exits on a refusal; a sweep over several must
+# refuse one desk and carry on to the next. The caller decides which.
+#
+# THE ORDER IS LOAD-BEARING AND IT IS THE MEASURED ONE:
+#
+# 1. THE PR, BEFORE THE STATE WORD. Five of five `failed` worktrees in this
+#    estate held a PR — four open, one already merged. `plot-worker-state.sh`
+#    refines `finished` by the tree but deliberately does NOT refine `failed`,
+#    `ended` or `none`, because a recorded non-zero exit is already a specific
+#    answer about the PROCESS — and silent about the WORK. A gate written on
+#    the state word alone would have restarted all five and discarded exactly
+#    what the `finished` refusal exists to protect.
+# 2. A LIVE WORKER. There is no --force: a flag overriding this is the flag
+#    typed reflexively, and what it would override is another agent's work in
+#    progress.
+# 3. A `PLOT-BLOCKED` MARKER. A person owes this branch an answer, and a new
+#    worker meets the same question and writes the same marker. Asked through
+#    `plot_worker_blocked_file`, never re-globbed: the marker's spelling lives
+#    with the classification in `plot-worker-state.sh` and only there.
+#
+# `stalled`, `failed`, `ended` and `no worker` all pass. The PR question is what
+# makes `failed` safe to include — and including it is the point: a gate that
+# simply refused `failed` would pass every refusal test and leave the verb
+# unable to do the one thing it exists for.
+handover_refusal() { # $1=branch $2=worktree $3=state → 0 may hand over, 1 refused
+  local branch="$1" wt="$2" state="$3" pr_json pr_num pr_state marker
+
+  if reached_review "$branch"; then
+    pr_json=$("$script_dir/plot-host.sh" pr-state "$branch" </dev/null 2>/dev/null || true)
+    pr_num=$(printf '%s' "$pr_json" | sed -n 's/.*"number":\([0-9]*\).*/\1/p')
+    pr_state=$(printf '%s' "$pr_json" | sed -n 's/.*"state":"\([A-Z]*\)".*/\1/p')
+    echo "plot-dispatch: $branch has a pull request (#${pr_num:-?}, ${pr_state:-OPEN}) — refusing." >&2
+    echo "  The work reached review, whatever the worker's exit code says. A" >&2
+    echo "  restart here redoes work someone is already looking at." >&2
+    echo "  Review it, or reap the worktree once it merges." >&2
+    return 1
+  fi
+
+  case "$state" in
+    running*)
+      echo "plot-dispatch: a worker is alive on $branch (pid ${state#running }) — refusing." >&2
+      echo "  Stop it first if you mean to replace it:" >&2
+      echo "    plot-dispatch.sh --stop $branch" >&2
+      return 1
+      ;;
+    waiting*)
+      marker=$(plot_worker_blocked_file "$wt" || true)
+      echo "plot-dispatch: $branch is blocked on a question — refusing." >&2
+      echo "  the question is in $wt/${marker:-the marker file}" >&2
+      echo "  Answer it and delete the marker, then restart." >&2
+      return 1
+      ;;
+  esac
+  return 0
+}
+
 start_worker() {
   local branch="$1" wt="$2"
   local cmd
+
+  # RESOLVED BEFORE `Worker command`, because the charter is the more specific
+  # answer and the config key is the fallback rather than the sole source.
+  #
+  # THE REFUSAL FIRES HERE, WHICH IS BEFORE ANYTHING THIS FUNCTION WRITES. The
+  # plan asks for a refusal "before the desk is touched"; on this codebase the
+  # desk already exists by the time `start_worker` is called — both call sites
+  # (`--restart`, and `--start`'s `git worktree add`) hand it a worktree path.
+  # What this position does guarantee is that NO WORKER IS LAUNCHED, no manifest
+  # is written and no `.plot-worker.exit` is removed, and `start_worker` pushes
+  # no claim at all — so the slice stays claimable by an agent that can run it,
+  # which is the property the plan's sentence is protecting. A desk with no
+  # worker is what `--start` already creates for a free agent, and the reaper
+  # handles it. See the PR body.
+  if ! resolve_launch "$repo_root" "${PLOT_AGENT:-}"; then
+    echo "  refusing to start ${branch:-a free agent} — $launch_why" >&2
+    echo "    A charter that cannot be read is a person's typo, and the repo's 'Worker command'" >&2
+    echo "    would run successfully under an invocation nobody asked for." >&2
+    echo "    Fix $repo_root/.plot/charters/${PLOT_AGENT:-?}.json, or unset PLOT_AGENT to start it" >&2
+    echo "    on the repo's configured command deliberately." >&2
+    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
@@ -1003,6 +1209,67 @@ start_worker() {
   # A HAND-MADE WORKTREE GETS NEITHER, and that falls out rather than being
   # enforced: this is the only code that starts a wrapper, and a worktree with
   # no wrapper has nothing for a monitor to be a child of.
+  # WHAT THIS AGENT MAY TOUCH — `PLOT_CAPABILITIES`, AND WHY IT IS RESOLVED HERE.
+  #
+  # A charter's `capabilities` list is the one differentiation Plot can express
+  # that is not a rule. Everything else an agent is told is PROSE — text it reads
+  # and can reason past — and CLAUDE.md's own test settles what that makes it:
+  # *can you answer "did I complete this?" without doing the work?* An agent
+  # asked in prose not to edit the code it reviews can answer yes without it
+  # being true. A tool the harness never offers cannot be called.
+  #
+  # RESOLUTION, NEVER MATCHING, the rule `plot-worker-loop.sh:916` states for the
+  # prompt. `$PLOT_AGENT` is what the operator or the registry set; nothing here
+  # reads a plan, ranks a candidate or chooses an agent. This slice BOUNDS an
+  # agent and does not route to one — `matchQueue` is the assignment lock and is
+  # untouched.
+  #
+  # THE LIST TRAVELS, THE SPELLING DOES NOT. Plot carries capability NAMES and
+  # has no opinion about what they mean: Principle 5, *"Plot contains zero
+  # hardcoded project names, paths, or configuration"*. Different harnesses spell
+  # a tool restriction differently, so the prompt file turns a name into a flag —
+  # the same division the prompt itself draws. There is no capability enum here,
+  # no built-in `read-only`, and no tool table in the domain.
+  #
+  # ASKED OF THE BUNDLE, NOT OF THE FILE. `plot-prompt.mjs` already reads this
+  # charter through `readCharter`, which refuses an unknown key, a run fact and
+  # bytes that are not JSON. A `grep` for the field would happily read
+  # capabilities out of a charter the domain refuses outright.
+  #
+  # AN EXIT CODE, NOT AN EMPTINESS. Three readings print nothing on stdout and
+  # only one of them is a fault: no agent named, and a named agent with no
+  # charter on this clone, are the estate today; a charter that EXISTS and cannot
+  # be believed is a person's typo, and exits 3. Launching unbounded on it would
+  # run — successfully — under a scope nobody asked for.
+  #
+  # NOTHING IS EXPORTED WHERE NOTHING WAS DECLARED. An agent with no charter, or
+  # one naming no capabilities, exports no `PLOT_CAPABILITIES` at all — not an
+  # empty string. A prompt file probes `[ -n "$PLOT_CAPABILITIES" ]`, and a
+  # variable that is always set makes that probe meaningless.
+  #
+  # THE BUNDLE MISSING IS NOT A REFUSAL, `resolve_prompt_file`'s fourth arm: a
+  # checkout without it is a Plot installation problem rather than a statement
+  # about this agent. It says it could not ask and launches unbounded, which is
+  # what it did before this existed.
+  local capabilities='' cap_status=0
+  if [ -n "${PLOT_AGENT:-}" ]; then
+    if [ -f "$script_dir/board/plot-prompt.mjs" ]; then
+      capabilities=$(node "$script_dir/board/plot-prompt.mjs" --capabilities "$repo_root" "$PLOT_AGENT" 2>/dev/null)
+      cap_status=$?
+      if [ "$cap_status" -eq 3 ]; then
+        echo "    refusing to start $branch — the charter for agent '$PLOT_AGENT' cannot be read:"
+        node "$script_dir/board/plot-prompt.mjs" --capabilities "$repo_root" "$PLOT_AGENT" 2>&1 >/dev/null \
+          | sed 's/^/      /'
+        echo "      A charter that cannot be believed must not launch an agent, because the"
+        echo "      launch would succeed under a scope nobody asked for. Fix"
+        echo "      $repo_root/.plot/charters/$PLOT_AGENT.json or unset PLOT_AGENT."
+        return 1
+      fi
+    else
+      echo "    no plot-prompt.mjs beside this script — starting $branch without asking what agent '$PLOT_AGENT' may touch"
+    fi
+  fi
+
   local worker_monitor='' agent_monitor='' build_monitor=''
   [ -x "$script_dir/plot-worker-monitor.sh" ] && worker_monitor="$script_dir/plot-worker-monitor.sh"
   [ -x "$script_dir/plot-agent-monitor.sh" ] && agent_monitor="$script_dir/plot-agent-monitor.sh"
@@ -1014,9 +1281,38 @@ start_worker() {
   [ -x "$script_dir/plot-build-monitor.sh" ] && build_monitor="$script_dir/plot-build-monitor.sh"
   local stamp_now
   stamp_now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-  ( cd "$wt" && PLOT_BRANCH="$branch" PLOT_WORKTREE="$wt" \
+  # THE THREE NAMES THE CHARTER DECLARED, and they travel as env vars for the
+  # reason every other path here does: the `sh -c` body is single-quoted, so a
+  # value with spaces would not survive interpolation into it.
+  #
+  # EMPTY IS THE ESTATE TODAY and must stay indistinguishable from before. An
+  # agent with no charter exports three empty strings, a prompt file
+  # interpolating `${PLOT_MODEL:-}` gets nothing, and the command line is
+  # byte-identical to what it was — which is the 100% case, since zero charters
+  # exist. `PLOT_AGENT` is forwarded too, so the loop's own `resolve_prompt_file`
+  # asks about the same agent this launch resolved.
+  ( cd "$wt" && \
+      # AN `export`, NOT AN ENV PREFIX, AND THE REASON IS A MEASUREMENT. Bash
+      # recognises an assignment prefix BEFORE it expands parameters, so a
+      # `${caps:+PLOT_CAPABILITIES="$caps"}` in the prefix below is not an
+      # assignment at all — it expands to a WORD, and bash then looks for a
+      # command by that name. Measured 2026-09-12: the empty case passed and
+      # every non-empty one failed with `PLOT_CAPABILITIES=read-only: command
+      # not found`, which would have broken every dispatch that had a charter
+      # while the case with no charter went on working.
+      #
+      # The conditional is what keeps an undeclared agent's variable UNSET
+      # rather than empty, so a prompt file's `[ -n "$PLOT_CAPABILITIES" ]`
+      # probe means what it says. This subshell is already the launch's own, so
+      # the export reaches the wrapper and nothing else.
+      { [ -n "$capabilities" ] && export PLOT_CAPABILITIES="$capabilities"; true; } && \
+      PLOT_BRANCH="$branch" PLOT_WORKTREE="$wt" \
       PLOT_SLUG="$slug" \
       PLOT_SESSION_ID="$session" \
+      PLOT_AGENT="${PLOT_AGENT:-}" \
+      PLOT_HARNESS="$launch_harness" \
+      PLOT_MODEL="$launch_model" \
+      PLOT_EFFORT="$launch_effort" \
       PLOT_MANIFEST_FILE="$manifest_dir/$session.json" \
       PLOT_STAMP_STARTED="$stamp_now" \
       PLOT_WORKER_MONITOR="$worker_monitor" \
@@ -1063,6 +1359,30 @@ start_worker() {
   return 0
 }
 
+# `PLOT_DISPATCH_SOURCED=1` STOPS HERE, so a test can take `resolve_launch` and
+# `start_worker` without dispatching anything — `plot-worker-loop.sh` states
+# this idiom for `resolve_prompt_file`, and this is the same one applied to the
+# functions that answer the same question one script over.
+#
+# AFTER BOTH DEFINITIONS IT EXISTS TO EXPOSE, and that placement is the whole
+# subtlety. This file is not `plot-worker-loop.sh`, where every definition
+# precedes every executing line: here the argument parsing runs at the TOP and
+# the functions are defined below it. Measured while writing this: a guard at
+# the top of the file returned before `resolve_launch` existed
+# (`resolve_launch: command not found`), and a guard between the two functions
+# hid `start_worker` the same way — which is the one a test must call to prove
+# a refusal touches no desk.
+#
+# `script_dir` IS ALREADY RESOLVED at this point, which is what a sourcing test
+# needs and what slicing the file cannot give it: `script_dir` is derived from
+# `BASH_SOURCE`, so a copy written to /tmp resolves every helper to /tmp.
+#
+# THE FLAG IS OPT-IN AND NAMED FOR THIS FILE. An unset variable leaves the
+# script exactly as it was — no caller changes, and a dispatched worker cannot
+# reach this return by accident. `return` rather than `exit` because a sourced
+# script returns to its sourcer.
+[ -n "${PLOT_DISPATCH_SOURCED:-}" ] && return 0
+
 # ---------------------------------------------------------------------------
 # Inspection and shutdown
 # ---------------------------------------------------------------------------
@@ -1278,44 +1598,12 @@ if [ "$mode" = "restart" ]; then
   # Same lesson plot-reap.sh learned from the other side: it reads `mergedAt`
   # and never `state`, because a merged PR reports CLOSED. There the state word
   # lies about merging; here the exit code lies about completion.
-  if reached_review "$restart_branch"; then
-    pr_json=$("$script_dir/plot-host.sh" pr-state "$restart_branch" </dev/null 2>/dev/null || true)
-    pr_num=$(printf '%s' "$pr_json" | sed -n 's/.*"number":\([0-9]*\).*/\1/p')
-    pr_state=$(printf '%s' "$pr_json" | sed -n 's/.*"state":"\([A-Z]*\)".*/\1/p')
-    echo "plot-dispatch: $restart_branch has a pull request (#${pr_num:-?}, ${pr_state:-OPEN}) — refusing." >&2
-    echo "  The work reached review, whatever the worker's exit code says. A" >&2
-    echo "  restart here redoes work someone is already looking at." >&2
-    echo "  Review it, or reap the worktree once it merges." >&2
-    exit 1
-  fi
 
   # Only now the process. `worker_state` is the ONE answer to "is a worker
   # running here" — asked rather than re-derived, so this cannot drift from
   # `--status` and the scan the way five of six states already did once.
   restart_state=$(worker_state "$restart_wt" "$restart_branch")
-  case "$restart_state" in
-    running*)
-      # THE REFUSAL THAT PREVENTS TWO WORKERS ON ONE BRANCH. There is no
-      # --force: a flag overriding this is the flag typed reflexively, and what
-      # it would override is another agent's work in progress.
-      echo "plot-dispatch: a worker is alive on $restart_branch (pid ${restart_state#running }) — refusing." >&2
-      echo "  Stop it first if you mean to replace it:" >&2
-      echo "    plot-dispatch.sh --stop $restart_branch" >&2
-      exit 1
-      ;;
-    waiting*)
-      # A person owes this branch an answer. A new worker meets the same
-      # question and writes the same marker.
-      # ASKED, NOT RE-GLOBBED. The marker's spelling lives with the
-      # classification in plot-worker-state.sh and only there; a copy of the
-      # glob here is the drift `workerstate.test.mjs` pins against.
-      marker=$(plot_worker_blocked_file "$restart_wt" || true)
-      echo "plot-dispatch: $restart_branch is blocked on a question — refusing." >&2
-      echo "  the question is in $restart_wt/${marker:-the marker file}" >&2
-      echo "  Answer it and delete the marker, then restart." >&2
-      exit 1
-      ;;
-  esac
+  handover_refusal "$restart_branch" "$restart_wt" "$restart_state" || exit 1
   # `stalled`, `failed`, `ended` and `no worker` all restart. The PR question
   # above is what makes `failed` safe to include — and including it is the
   # point: a gate that simply refused `failed` would pass every refusal test