@plot-pm/board 0.14.0 → 0.14.2

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
@@ -834,6 +928,47 @@ jenkins_no_instance() {
 # estimate for. This draws it one step earlier, for a connector that does not
 # exist at all — and `resultOf` (`adapters/run-script.ts:211`) maps exit 4 onto
 # `unaskable`, which is the word the build port already answers with.
+# The Jenkins REST credential, read from where `jen` already stores it.
+#
+# NOT THE KEYCLOAK BEARER. `jen auth token` prints one and Jenkins answers it
+# with an HTML login redirect — measured 2026-09-10, and it is the trap that
+# made an earlier reading conclude the sha was unreachable. Jenkins' own API
+# takes BASIC auth with a user and an API token, which `jen` keeps in the login
+# keychain under service `jen`, accounts `jenkins-user:<host>` and
+# `jenkins-token:<host>`.
+#
+# IT PRINTS `user:token` AND NOTHING ELSE, or nothing at all. The caller passes
+# it straight to `curl -u`; no branch echoes it, and no failure path names it.
+#
+# EMPTY IS THE HONEST ANSWER on a machine with no `security` (Linux, CI), with
+# no keychain entry, or with either half missing — a half credential is not a
+# credential. The caller turns that into exit 4, which is *cannot be asked*.
+jenkins_rest_credential() { # $1 = the bare host
+  command -v security >/dev/null 2>&1 || return 1
+  local u t
+  u=$(security find-generic-password -s jen -a "jenkins-user:$1" -w 2>/dev/null) || return 1
+  t=$(security find-generic-password -s jen -a "jenkins-token:$1" -w 2>/dev/null) || return 1
+  [ -n "$u" ] && [ -n "$t" ] || return 1
+  printf '%s:%s' "$u" "$t"
+}
+
+# A job path as Jenkins' REST API spells it: every segment under `job/`.
+#
+# `quaweb/release` is the path a person writes and `job/quaweb/job/release` is
+# the URL, because a Jenkins folder is itself a job. A multibranch branch adds
+# one more segment, PERCENT-ENCODED — `bug/foo` is `bug%2Ffoo`, the same
+# encoding `jenkins_build_map` already decodes on the way back.
+jenkins_job_url_path() { # $1 = job path, $2 = branch or ""
+  local out="" seg
+  local IFS=/
+  for seg in $1; do [ -n "$seg" ] && out="$out/job/$seg"; done
+  unset IFS
+  if [ -n "${2:-}" ]; then
+    out="$out/job/$(printf '%s' "$2" | sed 's|/|%2F|g')"
+  fi
+  printf '%s' "$out"
+}
+
 ci_unaskable() { # $1 = the op's name, $2 = the CI word (may be empty)
   local ci_word="${2:-}"
   if [ -z "$ci_word" ] || [ "$ci_word" = none ]; then
@@ -1722,12 +1857,47 @@ backend_declared() {
     return
   fi
   local v
-  v="$(bash "$here/plot-config.sh" get "Git host" "github" | tr '[:upper:]' '[:lower:]')"
+  v="$(bash "$here/plot-config.sh" get "Git host" "" | tr '[:upper:]' '[:lower:]')"
   case "$v" in
-    bb) echo "bitbucket" ;;
-    "") echo "github" ;;
-    *) printf '%s\n' "$v" ;;
+    bb) echo "bitbucket"; return ;;
+    "") : ;;
+    *) printf '%s\n' "$v"; return ;;
   esac
+
+  # NOTHING DECLARED — INFER FROM THE REMOTE, AND REFUSE WHERE THERE IS NONE.
+  # This answered `github` unconditionally until 2026-09-11, which is the
+  # reassuring direction: a Bitbucket repo that forgot the key got GitHub's
+  # answer, and a repo with no remote at all got one too. Measured on a fresh
+  # `git init` with no remote: `backend` printed `github` and exited 0.
+  #
+  # THE REMOTE IS EVIDENCE AND THE KEY IS A DECLARATION, so the key still wins
+  # above. What changes is only the case where nobody said: a hostname in the
+  # remote is a reading, and no remote is no reading.
+  local url
+  url="$(git config --get remote.origin.url 2>/dev/null || true)"
+  case "$url" in
+    *github.com*)    echo "github";    return ;;
+    *bitbucket.org*) echo "bitbucket"; return ;;
+  esac
+
+  # NOTHING NAMES A HOST, AND THAT IS REPORTED RATHER THAN REFUSED. An earlier
+  # version of this returned exit 4 here, and five contract tests went red:
+  # a sandbox repository with no remote is a legitimate, common shape — six
+  # suites build one — and every op that needs a host in one was relying on
+  # this default. Refusing at the resolver punishes them for a question they
+  # never asked.
+  #
+  # SO THE GUESS SURVIVES AND STOPS BEING SILENT — AND IT SIGNALS THROUGH THE
+  # EXIT CODE, NEVER A VARIABLE. This set a `BACKEND_UNNAMED` global first, and
+  # the caller reads it as `v="$(backend_declared)"` — a COMMAND SUBSTITUTION,
+  # which runs in a subshell, so the assignment died with the child and the
+  # parent always read 0. The warning never printed, and a direct call looked
+  # correct because its stdout was right.
+  #
+  # Exit 9 is arbitrary and deliberately outside the contract's 0/1/3/4: it
+  # never leaves this file, and `backend` maps it back to a successful answer.
+  echo "github"
+  return 9
 }
 
 # The resolved backend, refused where this script has no arm for it.
@@ -1740,12 +1910,27 @@ backend_declared() {
 # person must fix. `host-shell.ts` reads that code as `unaskable` and reads the
 # sentence below for the name.
 backend() {
-  local v
-  v="$(backend_declared)" || return 1
+  local v rc unnamed=0
+  # THE DECLARED-HOST REFUSAL IS PASSED THROUGH, NOT FLATTENED. `|| return 1`
+  # collapsed exit 4 into 1 here, and 4 is the one code every caller reads as
+  # *this cannot be asked at all* rather than *retry*. Measured 2026-09-11: a
+  # repository with no remote exited 1, which tells a caller to try again.
+  v="$(backend_declared)"; rc=$?
+  # 9 is the resolver's private word for *answered, but nothing named it*.
+  if [ "$rc" -eq 9 ]; then unnamed=1; rc=0; fi
+  [ "$rc" -eq 0 ] || return "$rc"
   if ! host_drivable "$v"; then
     echo "plot-host: cannot drive '$v' — this script drives ${HOST_DRIVES// /, }; set the 'Git host' key in CLAUDE.md (or \$PLOT_HOST) to one of them" >&2
     return 4
   fi
+  # THE ANSWER IS PRINTED EITHER WAY, AND A GUESS SAYS SO. `backend` is a
+  # reading, not a gate: a caller that needs a host still gets one, and a
+  # person asking which host this is learns the answer was inferred from
+  # nothing. Exit stays 0 — the value is usable, its provenance is not certain.
+  if [ "$unnamed" = 1 ]; then
+    echo "plot-host: no 'Git host' key and no remote names one — assuming '$v'" >&2
+    echo "  Set the 'Git host' key in ## Plot Config (or \$PLOT_HOST) to be sure." >&2
+  fi
   printf '%s\n' "$v"
 }
 
@@ -2991,29 +3176,100 @@ case "$op" in
     _ci="$(ci_scheme)"
     case "$_ci" in
       jenkins)
-        # JENKINS CANNOT ANSWER THIS THROUGH `jen`, AND THAT IS A MEASUREMENT
-        # RATHER THAN A GAP LEFT OPEN. `jenkins_build_map` — the only Jenkins
-        # reader this script has — answers `{color, checks, job}` per BRANCH and
-        # carries no commit at all, so there is nothing here to match a sha
-        # against.
+        # THE SHA IS IN JENKINS AND `jen` IS NOT THE TRANSPORT. Measured
+        # 2026-09-10 against a live instance: a build entry from `jen build
+        # list --json` carries `id`, `status`, timings and stages, and a search
+        # of the whole payload for `sha|commit|revision|scm` matches nothing.
+        # `jen` has no changesets subcommand and no raw-API passthrough.
+        #
+        # JENKINS' OWN REST API ANSWERS IT, at
+        # `actions[].lastBuiltRevision.SHA1`, paired with the branch. One
+        # `tree=` query returns a whole history — 4855 bytes for five builds —
+        # so this costs one round trip like the GitHub arm does.
+        #
+        # THIS ARM EXITED 4 UNTIL 2026-09-11, and the refusal was honest for
+        # the transport it had. What changed is the transport, not the rule.
+        _jen_instance="$(jenkins_instance)"
+        [ -n "$_jen_instance" ] || jenkins_no_instance
+        _jen_host="${_jen_instance%%/*}"
+        _jen_job="${_jen_instance#*/}"
+        [ "$_jen_job" = "$_jen_instance" ] && _jen_job=""
+        [ -n "${PLOT_JENKINS_JOB:-}" ] && _jen_job="$PLOT_JENKINS_JOB"
+        if [ -z "$_jen_job" ]; then
+          # A bare-host instance names no job, and a sha lives in a job's
+          # builds. `runs` degrades to an empty map here; this op has no row to
+          # carry that, so the only way to say *cannot be asked* is exit 4.
+          echo "plot-host: run-for-sha — the Jenkins instance names no job path" >&2
+          echo "  A sha is a fact about a job's builds, so the instance must be" >&2
+          echo "  <slug>/<job/path> rather than a bare host." >&2
+          exit 4
+        fi
+        _jen_cred="$(jenkins_rest_credential "$_jen_host")" || {
+          # NO CREDENTIAL IS *CANNOT BE ASKED*, never *no run*. The keychain is
+          # macOS-only and a Linux agent legitimately has none; saying nothing
+          # at exit 0 would read as a branch that never built.
+          echo "plot-host: run-for-sha — no Jenkins API credential for '$_jen_host'" >&2
+          echo "  Jenkins' REST API takes basic auth with an API token, which" >&2
+          echo "  \`jen auth login\` stores in the login keychain. The Keycloak" >&2
+          echo "  bearer from \`jen auth token\` is NOT it — Jenkins answers that" >&2
+          echo "  with a login redirect." >&2
+          exit 4
+        }
+        # A BRANCH IS A JOB SEGMENT ON A MULTIBRANCH JOB AND NOT ON A PLAIN
+        # ONE, and no reading of the configured path says which this is. So the
+        # multibranch URL is tried first and the plain one is the fallback:
+        # `job/quaweb/job/continuous-build/job/content%2Fctas` against
+        # `job/quaweb/job/release`. Measured 2026-09-11 — asking the plain job
+        # for a branch segment answers 404, which is why guessing one shape
+        # cost a run.
         #
-        # THE ANSWER EXISTS AND THIS TRANSPORT DOES NOT REACH IT. Measured
-        # 2026-09-08 against a live instance, a build names its commit at
-        # `actions[].BuildData.lastBuiltRevision.SHA1`, paired with its branch —
-        # over the REST API, which `the-ci-connector-is-jenkins` reads. Until
-        # that lands, `unaskable` is the true word: this connector cannot be
-        # asked, which is not the same as the branch having no run for the sha.
+        # THE PLAIN JOB REPORTS ITS OWN BUILDS whatever branch was asked about,
+        # and that is honest rather than wrong: a pipeline job builds one
+        # thing, and the `sha` in the answer says which commit it built.
+        _jen_tree="tree=builds%5Bnumber,result,building,timestamp,url,actions%5BlastBuiltRevision%5BSHA1%5D%5D%5D%7B0,$limit%7D"
+        _jen_body=""
+        for _jen_path in \
+          "$(jenkins_job_url_path "$_jen_job" "$branch")" \
+          "$(jenkins_job_url_path "$_jen_job" "")"; do
+          host_slot_take jenkins ''
+          _jen_try=$(curl -sg --max-time 30 -u "$_jen_cred" \
+            "https://$_jen_host$_jen_path/api/json?$_jen_tree" 2>/dev/null) || true
+          host_slot_give
+          budget_record_call jenkins ''
+          if printf '%s' "$_jen_try" | jq -e 'has("builds")' >/dev/null 2>&1; then
+            _jen_body="$_jen_try"; break
+          fi
+        done
+        _jen_cred=""
+        if [ -z "$_jen_body" ] || ! printf '%s' "$_jen_body" | jq -e 'has("builds")' >/dev/null 2>&1; then
+          # AN UNREACHABLE INSTANCE IS NOT AN EMPTY HISTORY. A refused or
+          # redirected request answers HTML, which fails the `builds` test.
+          echo "plot-host: run-for-sha — Jenkins did not answer for '$_jen_host'" >&2
+          exit 4
+        fi
+        # THE SAME FALLBACK RULE AS THE GITHUB ARM, and it is inherited rather
+        # than invented: the asked-for sha if a build carries it, else the
+        # newest build, and `sha` says WHICH. A caller that could not tell the
+        # two apart would be back to the branch-scoped guessing this op ends.
         #
-        # FALLING BACK TO THE BRANCH'S CURRENT STATE WOULD BE THE ONE ANSWER
-        # THAT COSTS A MERGE. This op exists because a run for a superseded
-        # commit reads identically to a run for the current one, and reporting
-        # a branch-scoped state with no sha in it is exactly the guessing it was
-        # written to end — two merge waiters were stopped for it on 2026-08-30.
-        echo "plot-host: run-for-sha — jenkins has no sha-scoped answer through \`jen\`" >&2
-        echo "  \`jen job list\` reports one state per branch and names no commit." >&2
-        echo "  A build's sha is in Jenkins and reached over its REST API, which" >&2
-        echo "  the Jenkins build connector reads. Until then this cannot be asked." >&2
-        exit 4
+        # `result` is null while a build runs, which is Jenkins' own word for
+        # *in flight* — mapped to the `status`/`conclusion` split the contract
+        # already uses, so the shape does not fork per connector.
+        printf '%s' "$_jen_body" | jq -c --arg sha "$sha" '
+          [ .builds[]
+            | { sha: ([ .actions[]? | select(.lastBuiltRevision) | .lastBuiltRevision.SHA1 ] | first // ""),
+                status: (if .building then "in_progress" else "completed" end),
+                conclusion: (if .building then null else (.result // null) end),
+                url: (.url // ""),
+                startedAt: (if .timestamp then (.timestamp / 1000 | todate) else "" end) } ]
+          | ((map(select(.sha == $sha)) | .[0]) // .[0])
+          | select(. != null)' 2>/dev/null || true
+        # THIS ARM ANSWERS AND THE OP IS OVER. Everything below the `esac` is
+        # the GitHub path — the old jenkins arm reached it only because it
+        # ended in `exit 4`. Measured 2026-09-11: without this the answer was
+        # printed and then a `CI is github-actions but the git host is
+        # 'bitbucket'` refusal followed it on stderr.
+        exit 0
         ;;
       github-actions) : ;;
       *) ci_unaskable run-for-sha "$_ci" ;;

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
   }