@plot-pm/board 0.14.1 → 0.14.2

package/package.json

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

@@ -419,6 +419,64 @@ decide_transition() { # $1=file  → prints "<Phase>\t<record>\t<write|already>"
 # writes — and appending a second is how one plan came to hold two `Delivered:`
 # lines (2026-09-01). The domain returns the written record unchanged in that
 # case, so the phase still flips and nothing is inserted.
+# Would the PARSER read this phase out of the file we are about to land?
+#
+# THE WRITE SUCCEEDING IS NOT THE OUTCOME HOLDING, and that gap is #924. A plan
+# carrying BOTH front matter and a `## Status` block was delivered in a project
+# repo: `flip_phase` wrote `Delivered` into the block, `mv` landed it, the
+# summary said `phase=flipped`, and `plot-plan-meta.sh` went on answering
+# `approved` — because it prefers front matter wherever it exists and reads the
+# block only in the `else if` below. The write took effect on bytes nobody
+# reads.
+#
+# `flip_phase`'s awk matches only inside `section == "status"`. That one guard
+# IS the defect: on a front-matter plan it edits the block and leaves the front
+# matter untouched, and returns 0 for having changed something.
+#
+# SO THE TEST IS WHAT THE PARSER ANSWERS, NEVER WHETHER AWK CHANGED A LINE.
+# Refusing on `flipped=0` would break every re-run of a correct delivery — a
+# plan already carrying `Delivered` flips nothing and is fine. This asks the one
+# question that distinguishes them: read the scratch copy the way every later
+# consumer will read the plan, and compare.
+#
+# IT RUNS ON THE SCRATCH COPY, BEFORE THE `mv`, and the caller passes whichever
+# file that arm is about to land — `$a` on the `recorded=yes` arm, `$b` on the
+# other. Parsing `$a` on the record arm would check content that never reaches
+# the plan. After the `mv` is too late twice over: the script's own header
+# documents exit 0 as *"the plan is Delivered on the default branch"*, so
+# refusing there would exit 1 on a run meeting the documented success
+# condition — and `runAutoDeliver` spawns this detached, logging a non-zero exit
+# to nobody while the plan sits delivered on main.
+#
+# AN UNREADABLE SCRATCH COPY REFUSES. `decide_transition` already takes that
+# line — *"refusing rather than guessing"* — and a file the parser cannot read
+# is exactly the state this gate exists to keep off the plan.
+phase_would_read() { # $1=scratch file $2=expected phase (lowercase) → 0 agrees, 1 refuses
+  local scratch="$1" want="$2" m got
+  m=$(bash "$script_dir/plot-plan-meta.sh" "$scratch" 2>/dev/null) || m=""
+  if [ -z "$m" ]; then
+    echo "plot-deliver: $rel — the written file does not parse, so the delivery was not landed." >&2
+    echo "  Nothing was written. Re-run after fixing the file." >&2
+    return 1
+  fi
+  got=$(printf '%s' "$m" | jq -r '.phase // ""')
+  [ "$got" = "$want" ] && return 0
+
+  # THE REFUSAL NAMES BOTH VALUES AND THE FILE. A message saying only "delivery
+  # failed" throws away the half a person acts on: which phase was written, and
+  # which one the parser still reads. The cause is named too, because the file
+  # holding two records of one fact is the thing to fix — and which format ought
+  # to win is a decision this gate deliberately leaves to a person.
+  echo "plot-deliver: $rel — wrote phase '$want', but the parser still reads '$got'." >&2
+  echo "  The plan states its phase in TWO places and they disagree: the write" >&2
+  echo "  landed in the '## Status' block while front matter takes precedence," >&2
+  echo "  so the delivery would have reported a success it did not achieve." >&2
+  echo "  Nothing was written — the plan is unchanged. Remove one of the two" >&2
+  echo "  records (front matter, or the '## Status' block) and re-run." >&2
+  echo "  See what the parser reads: $script_dir/plot-plan-meta.sh $rel" >&2
+  return 1
+}
+
 write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_report record_report
   local f="$1" record="$2" recorded="$3" a="$1.plot-phase" b="$1.plot-record" flipped=0
 
@@ -428,6 +486,11 @@ write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_repo
   [ -s "$a" ] || { rm -f "$a"; echo "plot-deliver: could not read $rel" >&2; return 1; }
 
   if [ "$recorded" = "yes" ]; then
+    # THE DRY RUN, on the file this arm is about to land. A refusal discards the
+    # scratch copy and leaves the plan byte-identical — and never reaches
+    # `record_state_receipt`, which would otherwise license a commit of a state
+    # that was refused.
+    phase_would_read "$a" delivered || { rm -f "$a"; return 1; }
     mv "$a" "$f" || { rm -f "$a"; return 1; }
     record_report="already"
   else
@@ -438,6 +501,9 @@ write_transition() { # $1=file $2=record $3=recorded(yes|no) → sets phase_repo
       echo "  with no record is invisible to the scan. Fix the section and re-run." >&2
       return 1
     fi
+    # `$b` AND NOT `$a`: this arm lands the file carrying the record, so `$a`
+    # is content that never reaches the plan.
+    phase_would_read "$b" delivered || { rm -f "$a" "$b"; return 1; }
     mv "$b" "$f" || { rm -f "$a" "$b"; return 1; }
     rm -f "$a"
     record_report="written"

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,17 +290,56 @@ 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
 
+# `--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
@@ -930,6 +989,42 @@ 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.
   #
@@ -1359,6 +1454,78 @@ 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

package/plot-host.sh

@@ -716,8 +716,41 @@ EOF
 #   failed  — Jenkins is unreachable (`jen auth status` says so, while EXITING
 #             0 — Done-when 4: the wording decides, never `$?`), or the listing
 #             was empty/garbled. `map` is {}; the caller renders rows `unknown`.
-#   unknown — the auth wording was unrecognised; degrade to failure-shaped
-#             (cannot verify), never to ok. `map` is {}.
+#   unknown — the auth wording was unrecognised, or the configured job is a
+#             SHAPE NOBODY MEASURED; degrade to failure-shaped (cannot verify),
+#             never to ok. `map` is {}.
+#
+# THE JOB'S SHAPE DECIDES THE VERB, and reading the shape off the wrong object
+# is the defect this function carried until 2026-09-15.
+#
+# `job list` enumerates a CONTAINER'S CHILDREN. A `WorkflowMultiBranchProject`
+# has one child per branch, so listing it yields exactly the branch→colour map
+# below. A plain `WorkflowJob` has no children, so the same call yields `null` —
+# not an error, not an empty array — and the `type=="array"` guard reported
+# `failed`, which is the word for an unreachable host. Measured live 2026-09-15
+# on `Quatico.Webseite/quaweb-website`: `job list quaweb/continuous-deploy`
+# answered `null` while `job view` on the same path answered `color blue`,
+# `lastBuild #938 SUCCESS`. A healthy, signed-in, correctly declared pipeline
+# read as *the connector cannot be asked*.
+#
+# THE DECIDING `_class` IS THE CONFIGURED JOB'S OWN, AND IT IS NOT IN THE
+# LISTING THIS FUNCTION ALREADY PERFORMS. A child's `_class` describes the
+# CHILD: measured live, every child of the multibranch `quaweb/continuous-build`
+# carries `...job.WorkflowJob`, and this repository's own fixture agrees. So
+# reading `.[0]._class` from the listing would read a healthy multibranch job as
+# plain, route it to `job view`, and break the half that works today — while
+# every gate still passed. That mistake sank an earlier draft of the plan.
+#
+# SO `job view` IS ASKED FIRST, and it answers BOTH questions in ONE call: the
+# job's own `_class`, and — for a plain job — the `color` and `lastBuild` that
+# are its state. The multibranch path then makes the single `job list` it has
+# always made, so a multibranch refresh costs two calls rather than one per
+# branch, and the branch→checks map it returns is byte-identical.
+#
+# EXACTLY TWO SHAPES ARE READ, and anything else is `unknown` rather than a
+# guess. A `FreeStyleProject` has a `color` and would be readable; it still
+# reports `unknown`, which is the honest word — *a shape nobody measured*. It is
+# deliberately NOT `failed`, which claims the host did not answer.
 jenkins_build_map() {
   local instance="$1"
   local slug job
@@ -751,6 +784,67 @@ jenkins_build_map() {
     printf '{"status":"unknown","map":{}}\n'; return 0
   fi
 
+  # THE SHAPE, READ FROM THE CONFIGURED JOB ITSELF. `job view` returns that
+  # job's own `_class` — never a child's — plus the `color` and `lastBuild` a
+  # plain job's state is made of. One call, two answers.
+  #
+  # A BARE-HOST INSTANCE NAMES NO JOB, so there is nothing to view: `job` is
+  # empty, the root scope has no `_class` of its own, and the multibranch path
+  # below already handles it by listing at the root. Probing with an empty path
+  # would ask about the instance rather than about a job.
+  local shape="" view_out=""
+  if [ -n "$job" ]; then
+    view_out=$(jen -I "$slug" job view "$job" --json 2>&1) || true
+    if [ -n "$view_out" ]; then
+      shape=$(printf '%s' "$view_out" | jq -r 'if type=="object" then (._class // "") else "" end' 2>/dev/null || echo "")
+    fi
+  fi
+
+  case "$shape" in
+    # A PLAIN PIPELINE — the case that reported `failed` until 2026-09-15. Its
+    # state is already in hand: `job view` answered it, and no `job list`
+    # follows, because listing a job with no children is what returned `null`.
+    #
+    # THE BRANCH KEY IS THE JOB PATH'S LAST SEGMENT. A plain job builds one
+    # thing and Jenkins names no branch for it, so there is no branch→colour
+    # map to build. Keying on the job's own name is what lets `.map[$branch]`
+    # find it — `runs` reads that key, and the op's caller asks by the name the
+    # instance declares.
+    *'.WorkflowJob')
+      printf '%s' "$view_out" | jq -c --arg job "$job" '
+        def color_to_checks:
+          if . == null or . == "" then "none"
+          elif endswith("_anime") then "pending"
+          elif . == "blue" then "green"
+          elif . == "red" or . == "yellow" then "failing"
+          else "none"
+          end;
+        ($job | split("/") | last) as $name
+        | { status: "ok",
+            map: { ($name): { color: .color,
+                              checks: (.color | color_to_checks),
+                              job: $job } } }
+      ' 2>/dev/null || printf '{"status":"failed","map":{}}\n'
+      return 0
+      ;;
+    *'.WorkflowMultiBranchProject')
+      : # fall through to the listing below — the path that has always worked
+      ;;
+    '')
+      # `job view` answered nothing usable. NOT a shape verdict: an instance
+      # naming no job reaches here by design, and so does a `jen` too old to
+      # know the verb. Fall through and let the listing decide, which is
+      # exactly what this function did before the probe existed.
+      :
+      ;;
+    *)
+      # A SHAPE NOBODY MEASURED. `unknown` says that; `failed` would claim
+      # Jenkins did not answer, when it answered clearly and said something
+      # this reader has never been taught to read.
+      printf '{"status":"unknown","map":{}}\n'; return 0
+      ;;
+  esac
+
   # One call, every branch — the spike's whole point (Done-when 5).
   local out=""
   out=$(jen -I "$slug" job list ${job:+"$job"} --json 2>&1) || true

package/plot-plan-meta.sh

@@ -150,6 +150,16 @@
 #                  BECAUSE annotations already work in both slice dialects from
 #                  one block of code — a field line would need two spellings,
 #                  and the template writes the list dialect.
+#                  `<!-- agent: reviewer -->` names which KIND of agent this
+#                  slice needs, reported as `waves[].branches[].agent` and read
+#                  by plot-dispatch.sh where `--agent` is absent. OPTIONAL, and
+#                  the key is ABSENT where none was written, never "" — dispatch
+#                  reads presence, so a blank would send it looking for a charter
+#                  called "". The value runs to the closing marker, as `builds:`
+#                  does. It CANNOT validate its value the way `waits:` does: a
+#                  charter name is a bare word with no structure to check, so a
+#                  template documents the marker inside an outer comment block,
+#                  where this pattern cannot see it.
 #   prs            PR numbers, sorted and unique, read from EITHER spelling:
 #                  `→ #NNN` / `→ owner/repo#NNN` links in the `## Branches`
 #                  section, OR `PR: #NNN` in a `## Waves` `### ` heading. The
@@ -424,6 +434,7 @@ function reset_state() {
   delete deferred_of; delete deferred_why; delete claimed_of; delete ordered_b; n_waves = 0
   delete waits_of; delete waits_set
   delete builds_of; delete builds_set
+  delete agent_of; delete agent_set
   delete started; n_started = 0
   fm_changelog = ""
   delete changelog; n_changelog = 0; changelog_seen = 0; cl_open = 0
@@ -584,6 +595,13 @@ function emit_record(   fmt, praw, palt_raw, traw, title, sprint, story, assigne
       # names no deliverable emits no key, so a consumer reads a name or
       # nothing. An empty string would read as a deliverable called "".
       if (builds_set[i] == 1) out = out ",\"builds\":\"" jesc(builds_of[i]) "\""
+      # ABSENT, NOT EMPTY, the rule the three annotations above already keep.
+      # Dispatch reads the PRESENCE of this key to decide whether the plan names
+      # a kind at all, so an `"agent":""` would read as a charter called "" and
+      # send it looking for `.plot/charters/.json`.
+      # NOTE: no apostrophe may appear in this awk region — the whole program is
+      # one single-quoted shell string, and one closes it mid-comment.
+      if (agent_set[i] == 1) out = out ",\"agent\":\"" jesc(agent_of[i]) "\""
       out = out "}"
       first = 0
     }
@@ -1012,6 +1030,44 @@ section == "slices" && slice_shape != "heading" {
     if (waits_note ~ "^(" PREFIXES ")/[^ \t]+$") has_waits = 1
     else waits_note = ""
   }
+  # WHICH KIND OF AGENT THIS SLICE NEEDS: `<!-- agent: reviewer -->`.
+  #
+  # `--agent <name>` was the only selector and only an operator could type it.
+  # `plot-registryd` 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. The declaration has to live in the PLAN to reach a
+  # dispatch nobody is watching.
+  #
+  # PER-BRANCH, NEVER A `## Status` FIELD. Every Status field is plan-level, so
+  # one there could declare a single kind for a plan with several slices — and a
+  # reviewer slice beside an implementer slice is the population this is for.
+  #
+  # The value runs to the closing marker, the way `builds:` does and unlike
+  # `waits:`. A charter name is a bare word today, so both rules agree; this one
+  # is chosen because it does not silently truncate if a name grows a space.
+  #
+  # IT CANNOT VALIDATE ITS VALUE, and that is the difference from `waits:` above.
+  # A prerequisite has branch-prefix structure, which is what keeps a SYNTAX
+  # EXAMPLE in prose from reading as a declaration; a charter name is a bare word
+  # with no structure to check. What protects the templates instead is NESTING:
+  # their documentation sits inside an outer `<!-- ... -->` block, so the inner
+  # `agent:` carries no `<!--` of its own and this pattern never matches it —
+  # the same accident of shape that already keeps `builds:` out of the parse of
+  # a template. Documenting it as a bare `<!-- agent: reviewer -->` line would
+  # hand a kind to every plan created from that template. A test pins it.
+  #
+  # `has_agent` carries presence separately from the value, as all three
+  # annotations before it do: a slice naming no kind emits no key, so dispatch
+  # reads a name or nothing and never a blank string that looks like one.
+  agent_note = ""
+  has_agent = 0
+  if ($0 ~ /<!--[ \t]*agent:[ \t]*/) {
+    _ag = $0
+    sub(/^.*<!--[ \t]*agent:[ \t]*/, "", _ag)
+    sub(/[ \t]*-->.*$/, "", _ag)
+    agent_note = trim(_ag)
+    if (agent_note != "") has_agent = 1
+  }
   # ONE LIST ITEM, AT MOST ONE CLAIM — an `if`, not the `while` this was.
   #
   # The old loop walked the line taking every backticked name on it, which is
@@ -1051,6 +1107,10 @@ section == "slices" && slice_shape != "heading" {
     waits_set[n_branches] = has_waits
     builds_of[n_branches] = builds_note
     builds_set[n_branches] = has_builds
+    # The kind travels with the branch, presence tracked separately so a slice
+    # declaring none emits no key.
+    agent_of[n_branches] = agent_note
+    agent_set[n_branches] = has_agent
     ordered_b[n_branches] = b
   }
   line = $0
@@ -1188,6 +1248,19 @@ section == "slices" && slice_shape == "heading" {
     if (waits_note ~ "^(" PREFIXES ")/[^ \t]+$") has_waits = 1
     else waits_note = ""
   }
+  # The agent kind, read exactly as the list-item spelling reads it. Both
+  # dialects emit the same waves[], so a field added to one only would break that
+  # contract the first time a plan migrated. See the list-item block for why the
+  # value runs to the closing marker and why this one cannot validate itself.
+  agent_note = ""
+  has_agent = 0
+  if ($0 ~ /<!--[ \t]*agent:[ \t]*/) {
+    _ag = $0
+    sub(/^.*<!--[ \t]*agent:[ \t]*/, "", _ag)
+    sub(/[ \t]*-->.*$/, "", _ag)
+    agent_note = trim(_ag)
+    if (agent_note != "") has_agent = 1
+  }
 
   # The branch is the `Branch:` value, matched against the known prefixes exactly
   # as the old shape matched the backticked name. Written unquoted in the heading
@@ -1211,6 +1284,8 @@ section == "slices" && slice_shape == "heading" {
     waits_set[n_branches] = has_waits
     builds_of[n_branches] = builds_note
     builds_set[n_branches] = has_builds
+    agent_of[n_branches] = agent_note
+    agent_set[n_branches] = has_agent
     ordered_b[n_branches] = b
   }