@plot-pm/board 0.14.0 → 0.14.2

package/plot-dispatch.sh

@@ -56,6 +56,25 @@
 #               tradition of --allow-local: a gate with no exit is one people
 #               route around by never annotating at all. It says so on the
 #               line it overrides, so the override is on the record.
+#   --agent <name>  dispatch this run's agents under the charter
+#               `.plot/charters/<name>.json`. It SETS `PLOT_AGENT`, which was
+#               the input all along and which nothing chose: the charter
+#               mechanism shipped in v2.17.0 with 16 readers for `harness` and
+#               no selector at all, so a kind could be declared and never
+#               asked for. The choice is EXPLICIT and never inferred — a
+#               matcher reading a plan could guess a kind, and a guess that is
+#               usually right produces a fleet whose wrong answers cannot be
+#               explained. An already-exported PLOT_AGENT is overridden, since
+#               a flag on this run is the more specific answer.
+#               AMENDED 2026-09-15: a slice may now DECLARE its kind, and
+#               `start_worker` reads it where this flag left `PLOT_AGENT`
+#               unset. That is not the matcher refused above — a declaration is
+#               a field a person wrote, and nothing here ranks candidates or
+#               infers a kind from a slice's contents. The flag still wins,
+#               because a flag typed on this run is more specific than a field
+#               written when the plan was drafted. A charter this clone does
+#               not hold is REPORTED and dispatched anyway; see
+#               `plan_declared_agent`.
 #   <slug>      the plan to fan out
 # Output: one line per branch, each optionally followed by an indented
 #         `in flight:` line naming a branch that already holds files, then the
@@ -230,6 +249,7 @@ allow_waiting=0
 max=0
 slug=""
 migrate_yes=0
+agent=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --dry-run)  dry_run=1 ;;
@@ -270,23 +290,70 @@ while [ $# -gt 0 ]; do
     --offline|--no-fetch) offline="--offline" ;;
     --allow-local) allow_local=1 ;;
     --allow-waiting) allow_waiting=1 ;;
+    # THE VALUE IS REQUIRED AND ALWAYS CONSUMED, which is the opposite of the
+    # rule `--stop`, `--restart` and `--start` follow — and the difference is
+    # the value's SHAPE rather than a change of mind. Those three take a branch
+    # (`*/*`) or a count (digits), each recognisable on sight, so an absent one
+    # can be left for the parser. An agent name is a bare word and so is a plan
+    # slug: nothing tells `--agent reviewer` from `--agent` followed by the
+    # slug. Leaving it unconsumed would let the `*)` arm below silently take
+    # the agent name as the plan to dispatch, which reads as "no such plan" and
+    # names neither what was asked nor what went wrong. So a missing value
+    # REFUSES rather than guessing.
+    --agent)    agent="${2:?--agent needs a charter name, e.g. --agent reviewer}"
+                case "$agent" in
+                  -*) echo "plot-dispatch: --agent needs a charter name, got '$agent'" >&2; exit 1 ;;
+                esac
+                shift ;;
     --max)      max="${2:?--max needs a value}"
                 case "$max" in
                   ''|*[!0-9]*) echo "plot-dispatch: --max needs a number, got '$max'" >&2; exit 1 ;;
                 esac
                 shift ;;
-    -h|--help)  sed -n '2,59p' "$0"; exit 0 ;;
+    # THE RANGE MOVED WITH THE HEADER IT PRINTS. It ended at `<slug>` and still
+    # does; adding `--agent` above pushed that line from 59 to 69, and
+    # documenting the plan-declared kind pushed it from 69 to 78. 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,78p' "$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 (usage: plot-dispatch.sh [--dry-run] <slug>)" >&2
-  echo "  Which plans could be dispatched: /plot-pulse" >&2
-  exit 1
-}
+# `--agent` SETS THE INPUT THAT ALREADY EXISTED, and it sets it in ONE place.
+#
+# `PLOT_AGENT` was read in three places before this flag — `resolve_launch`'s
+# call in `start_worker`, the `--capabilities` block, and the forwarded export
+# into the worker's environment — and assigned in none: `plot-dispatch.sh` held
+# `PLOT_AGENT="${PLOT_AGENT:-}"`, a pass-through of whatever the operator had
+# already exported. So the selector existed as a variable nothing chose.
+#
+# ONE ASSIGNMENT RATHER THAN A THREADED ARGUMENT. Every reader already asks
+# `${PLOT_AGENT:-}`; exporting here reaches all three with no further change and
+# leaves no call site that could be missed when a fourth reader is added. The
+# flag's whole meaning is "set PLOT_AGENT", which is also what keeps it from
+# becoming a second selector competing with the variable.
+#
+# THE FLAG WINS OVER AN INHERITED VALUE. A dispatched worker runs with its own
+# `PLOT_AGENT` in the environment, so a run launched from inside one would
+# otherwise inherit a kind nobody asked for on this dispatch.
+[ -n "$agent" ] && export PLOT_AGENT="$agent"
+
+# 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 +810,243 @@ 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
+
+  # THE PLAN IS THE DEFAULT AND THE FLAG IS THE OVERRIDE.
+  #
+  # `[ -z "${PLOT_AGENT:-}" ]` is the whole precedence rule: `--agent` exported
+  # the variable before this line was reached, so a flag typed on this run stops
+  # the plan being read at all. A field written when the plan was drafted is the
+  # less specific answer — the same order `--agent` already applies to an
+  # inherited `PLOT_AGENT`.
+  #
+  # ONE ASSIGNMENT, FOR THE REASON `--agent` GIVES ONE FIELD OVER. Four readers
+  # ask `${PLOT_AGENT:-}` — `resolve_launch` below, the capabilities block, the
+  # manifest, and the export into the worker environment — so setting the
+  # variable reaches all four and leaves no call site to miss when a fifth
+  # appears.
+  #
+  # A FREE AGENT HAS NO BRANCH and so has no plan to read: `--start` calls this
+  # with `branch` empty, and `plan_declared_agent` returns 1 on it immediately.
+  if [ -z "${PLOT_AGENT:-}" ] && [ -n "$branch" ]; then
+    local declared charter
+    if declared=$(plan_declared_agent "$branch"); then
+      export PLOT_AGENT="$declared"
+      # A MISSING CHARTER IS REPORTED AND DISPATCHED ANYWAY. Said HERE rather
+      # than only in the manifest, because this is where a person watching the
+      # run can still act on it: the launch below falls back to the repo default
+      # and is otherwise silent about a declaration that reached nothing.
+      charter=$(charter_file_for "$declared")
+      if [ -n "$charter" ] && [ ! -f "$charter" ]; then
+        echo "    $branch declares agent '$declared', and no charter answers to that name"
+        echo "      looked for $charter"
+        echo "      starting it on the repo's 'Worker command' — a plan written where that"
+        echo "      charter exists must stay dispatchable on a clone that lacks it."
+      else
+        echo "    $branch declares agent '$declared' — its plan selected the charter"
+      fi
+    fi
+  fi
+
+  # 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 +1304,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 +1376,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 +1454,102 @@ start_worker() {
   return 0
 }
 
+# WHICH KIND OF AGENT A BRANCH'S PLAN DECLARES — the selector nobody has to type.
+#
+# `--agent` was the only one, and an operator is the only thing that can type a
+# flag. The registry hands a queued slice to a free agent with no `--agent`
+# anywhere in the path, so an unattended fleet ran every slice as the same
+# undifferentiated worker. A plan that names the kind is what reaches a dispatch
+# nobody is watching.
+#
+# IT ANSWERS AND EXPORTS NOTHING. The caller decides, because the precedence is
+# the caller's: `--agent` already won over an inherited `PLOT_AGENT` and must win
+# over this too — a flag typed on this run is more specific than a field written
+# when the plan was drafted.
+#
+# THE PLAN DIRECTORY IS SEARCHED, NOT THE ACTIVE INDEX, and the candidates are
+# grepped before any is parsed — both `plot-open-pr.sh`'s rules, measured there:
+# a plan governing a branch may carry no symlink, and parsing 253 plans took
+# 103 s against 0.6 s for one `grep -lF` over the directory. A branch name is a
+# literal string, so a plan that does not contain it cannot name it.
+#
+# ABSENCE IS THE COMMON ANSWER AND NEVER AN ERROR. Every plan on the estate
+# names no kind, a `--restart` may run on a branch no plan names at all, and the
+# annotation is optional by design. All three print nothing and return 1.
+plan_declared_agent() { # $1 = branch → prints the declared kind, or nothing
+  local branch="$1" plan_dir root cands f found
+  [ -n "$branch" ] || return 1
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || return 1
+  plan_dir=$("$script_dir/plot-config.sh" get "Plan directory" "docs/plans/")
+  case "$plan_dir" in /*) ;; *) plan_dir="$root/$plan_dir" ;; esac
+
+  cands=$(grep -lF "$branch" "$plan_dir"*.md 2>/dev/null || true)
+  for f in $cands; do
+    [ -e "$f" ] || continue
+    # The PARSER answers, never a grep of the plan file. A `grep agent:` would
+    # read the marker out of prose documenting it and out of a DIFFERENT branch
+    # line in the same plan — the annotation binds to one branch, and only the
+    # parser knows which.
+    found=$(bash "$script_dir/plot-plan-meta.sh" "$f" 2>/dev/null \
+      | PLOT_WANT_BRANCH="$branch" node -e '
+        let s = "";
+        process.stdin.on("data", (d) => (s += d)).on("end", () => {
+          let meta;
+          try { meta = JSON.parse(s); } catch { return; }
+          const want = process.env.PLOT_WANT_BRANCH;
+          for (const wave of meta.waves ?? []) {
+            for (const b of wave.branches ?? []) {
+              // PRESENCE, not truthiness. The parser emits no `agent` key where
+              // the plan declares none, which is every plan on the estate.
+              if (b.branch === want && "agent" in b) { console.log(b.agent); return; }
+            }
+          }
+        });
+      ') || found=""
+    if [ -n "$found" ]; then printf '%s\n' "$found"; return 0; fi
+  done
+  return 1
+}
+
+# DOES THIS CLONE HOLD THE CHARTER? Answered so a MISSING one can be REPORTED.
+#
+# A DELIBERATE ASYMMETRY, and the plan settles it: `resolve_launch` refuses a
+# charter it cannot BELIEVE (malformed) and a harness not on PATH, and both
+# stay. A charter that simply does not EXIST is the adoption case — a plan
+# written where `reviewer` is declared, dispatched on a clone that declares
+# nothing — and refusing it would make that plan undispatchable on every such
+# clone. So the kind still travels, the launch falls back to the repo default,
+# and the run SAYS which name it looked for.
+charter_file_for() { # $1 = agent name → prints the path it would read
+  local name="$1" root
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || return 1
+  printf '%s/.plot/charters/%s.json\n' "$root" "$name"
+}
+
+# `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 +1765,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